tls: use options in getCACertificates() with X509Certificate

[haramj]

This PR implements the TODO(joyeecheung) note to support X509Certificate output in tls.getCACertificates(). It introduces a new format option, enhancing the function's flexibility and aligning its API with Node.js's broader crypto module.

The function's behavior is now extended as follows:
API Enhancement: Adds an optional format parameter to tls.getCACertificates() to specify the output format.

Output Options:

• 'pem' (default): Returns an array of PEM-encoded certificate strings. This is the new default to align with the name used in other Node.js crypto APIs.
• 'der': Returns an array of certificate data as Buffer objects in DER format.
• 'x509': Returns an array of crypto.X509Certificate instances, providing direct access to certificate properties.

[nodejs-github-bot]

Review requested:

• @nodejs/crypto
• @nodejs/net

[jasnell]

Suggested change

[joyeecheung]

It seems the white spaces are still there? Can you remove them?

[haramj]

Okay. I'll remove the white space

[haramj]

@joyeecheung Removing that white space will cause a format error in the document..

[haramj]

@jasnell Thank you very much for the thorough and detailed reviews.
I really appreciate the time and effort you’re putting into this.
I’ll carefully go through all the feedback and address them step by step.

Additionally,
When building the docs, the tooling failed to recognize the X509Certificate type and composite return types like Array<Buffer|X509Certificate>, causing errors.
I tried fixing type annotations, references, and escape characters, but I'd appreciate guidance on the correct way to document such composite types officially.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 89.70%. Comparing base (2263b4d) to head (625faaa).
⚠️ Report is 102 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #59349      +/-   ##
==========================================
+ Coverage   89.68%   89.70%   +0.01%     
==========================================
  Files         676      694      +18     
  Lines      206710   214253    +7543     
  Branches    39584    41123    +1539     
==========================================
+ Hits       185398   192188    +6790     
- Misses      13441    14109     +668     
- Partials     7871     7956      +85     

Files with missing lines	Coverage Δ
lib/tls.js	93.61% <100.00%> (+0.50%)	⬆️

... and 106 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[haramj]

The CI is failing due to a missing documentation anchor:
link not found: all_tls_tlsgetcacertificatestype
This seems unrelated to the changes in this PR — I didn’t modify that anchor or the associated section..

[haramj]

Hi, feedback has been addressed.
Is there anything else needed from me before this can move forward?

[haramj]

If you have some time, could you please review this? @nodejs/net, @joyeecheung

[jasnell]

LGTM! Great job. Let's ask @joyeecheung to also take a look since it was her TODO :-)

[haramj]

LGTM! Great job. Let's ask @joyeecheung to also take a look since it was her TODO :-)

Thank you so much for the review and the LGTM! I really appreciate your time.

During my final testing, I discovered an unexpected failure related to caching, and also found a minor inconsistency with the documentation. I would like to push a fix for those before the PR is ready to merge.

I'll push the updated changes shortly.

[haramj]

@jasnell @joyeecheung
I've confirmed that the logic using the map() method in the getCACertificates function is causing the caching-related assert.strictEqual test to fail, because it creates a new copy every time.

So I added the caching logic, but now other tests are failing.

[nodejs-github-bot]

CI: https://ci.nodejs.org/job/node-test-pull-request/69114/

[haramj]

@jasnell @joyeecheung

I've successfully implemented support for new formats by clearly separating the logic for object input while maintaining the existing function's behavior.

All tests have passed, and I believe the PR is ready for review.

Thank you.

[haramj]

Hi @joyeecheung,

I've refactored getCACertificates() to follow a clean, linear flow:

Normalize options to handle both string and object inputs.

Single retrieval using getCACertificatesAsStrings().

Process results based on the requested format.

This eliminates redundant calls and preserves caching for the default format. I also updated the tests to strictly verify data integrity using tlsCommon.assertEqualCerts()