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 90.14%. Comparing base (b2a024b) to head (b628c60).
⚠️ Report is 3 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #59349      +/-   ##
==========================================
- Coverage   90.15%   90.14%   -0.02%     
==========================================
  Files         744      744              
  Lines      242542   242579      +37     
  Branches    45690    45698       +8     
==========================================
+ Hits       218672   218679       +7     
- Misses      15362    15400      +38     
+ Partials     8508     8500       -8     

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

... and 28 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.

[joyeecheung]

It seems to me this can just reuse the original function; keep that as something like function getCACertificatesAsStrings(type = 'default'), and in function getCACertificates(options = undefined) you just normalize the options first, then get the array of strings, then process it from there.

[haramj]

@joyeecheung I've applied the feedback. Could you take a look?

[haramj]

Could you please take a look at this when you have a moment? Thanks! @joyeecheung

[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()

[github-actions]

This pull request has been marked as stale due to 90 days of inactivity.
It will be automatically closed in 30 days if no further activity occurs. If this is still relevant, please leave a comment or update it to keep it open.