feat(http): add ca option for custom TLS certificates

Add `ca` option to HttpRequestOptions, HttpDownloadOptions, and
FetchChecksumsOptions for custom CA certificate support. This enables
SSL_CERT_FILE support when NODE_EXTRA_CA_CERTS was not set at process
startup.

Thread ca through httpRequest, httpDownload, and fetchChecksums
including their redirect and retry paths. The ca option is passed
directly to Node.js https.request for TLS connections.

Author: jdalton

src/http-request.ts

@@ -100,6 +100,24 @@ export interface HttpRequestOptions {
    * ```
    */
   body?: Buffer | string | undefined
+  /**
+   * Custom CA certificates for TLS connections.
+   * When provided, these certificates are combined with the default trust
+   * store via an HTTPS agent. Useful when SSL_CERT_FILE is set but
+   * NODE_EXTRA_CA_CERTS was not available at process startup.
+   *
+   * @example
+   * ```ts
+   * import { rootCertificates } from 'node:tls'
+   * import { readFileSync } from 'node:fs'
+   *
+   * const extraCerts = readFileSync('/path/to/cert.pem', 'utf-8')
+   * await httpRequest('https://api.example.com', {
+   *   ca: [...rootCertificates, extraCerts]
+   * })
+   * ```
+   */
+  ca?: string[] | undefined
   /**
    * Whether to automatically follow HTTP redirects (3xx status codes).
    *
@@ -334,6 +352,12 @@ export interface HttpResponse {
  * Configuration options for file downloads.
  */
 export interface HttpDownloadOptions {
+  /**
+   * Custom CA certificates for TLS connections.
+   * When provided, these certificates are used for the download request.
+   * See `HttpRequestOptions.ca` for details.
+   */
+  ca?: string[] | undefined
   /**
    * Whether to automatically follow HTTP redirects (3xx status codes).
    * This is essential for downloading from services that use CDN redirects,
@@ -608,6 +632,11 @@ export function parseChecksums(text: string): Checksums {
  * Options for fetching checksums from a URL.
  */
 export interface FetchChecksumsOptions {
+  /**
+   * Custom CA certificates for TLS connections.
+   * See `HttpRequestOptions.ca` for details.
+   */
+  ca?: string[] | undefined
   /**
    * HTTP headers to send with the request.
    */
@@ -649,12 +678,16 @@ export async function fetchChecksums(
   url: string,
   options?: FetchChecksumsOptions | undefined,
 ): Promise<Checksums> {
-  const { headers = {}, timeout = 30_000 } = {
+  const {
+    ca,
+    headers = {},
+    timeout = 30_000,
+  } = {
     __proto__: null,
     ...options,
   } as FetchChecksumsOptions
 
-  const response = await httpRequest(url, { headers, timeout })
+  const response = await httpRequest(url, { ca, headers, timeout })
 
   if (!response.ok) {
     throw new Error(
@@ -675,6 +708,7 @@ async function httpDownloadAttempt(
   options: HttpDownloadOptions,
 ): Promise<HttpDownloadResult> {
   const {
+    ca,
     followRedirects = true,
     headers = {},
     maxRedirects = 5,
@@ -687,7 +721,7 @@ async function httpDownloadAttempt(
     const isHttps = parsedUrl.protocol === 'https:'
     const httpModule = isHttps ? getHttps() : getHttp()
 
-    const requestOptions = {
+    const requestOptions: Record<string, unknown> = {
       headers: {
         'User-Agent': 'socket-registry/1.0',
         ...headers,
@@ -699,6 +733,11 @@ async function httpDownloadAttempt(
       timeout,
     }
 
+    // Pass custom CA certificates for TLS connections.
+    if (ca && isHttps) {
+      requestOptions['ca'] = ca
+    }
+
     const { createWriteStream } = getFs()
 
     let fileStream: ReturnType<typeof createWriteStream> | undefined
@@ -739,6 +778,7 @@ async function httpDownloadAttempt(
 
           resolve(
             httpDownloadAttempt(redirectUrl, destPath, {
+              ca,
               followRedirects,
               headers,
               maxRedirects: maxRedirects - 1,
@@ -850,6 +890,7 @@ async function httpRequestAttempt(
 ): Promise<HttpResponse> {
   const {
     body,
+    ca,
     followRedirects = true,
     headers = {},
     maxRedirects = 5,
@@ -862,7 +903,7 @@ async function httpRequestAttempt(
     const isHttps = parsedUrl.protocol === 'https:'
     const httpModule = isHttps ? getHttps() : getHttp()
 
-    const requestOptions = {
+    const requestOptions: Record<string, unknown> = {
       headers: {
         'User-Agent': 'socket-registry/1.0',
         ...headers,
@@ -874,6 +915,11 @@ async function httpRequestAttempt(
       timeout,
     }
 
+    // Pass custom CA certificates for TLS connections.
+    if (ca && isHttps) {
+      requestOptions['ca'] = ca
+    }
+
     /* c8 ignore start - External HTTP/HTTPS request */
     const request = httpModule.request(
       requestOptions,
@@ -903,6 +949,7 @@ async function httpRequestAttempt(
           resolve(
             httpRequestAttempt(redirectUrl, {
               body,
+              ca,
               followRedirects,
               headers,
               maxRedirects: maxRedirects - 1,
@@ -1055,6 +1102,7 @@ export async function httpDownload(
   options?: HttpDownloadOptions | undefined,
 ): Promise<HttpDownloadResult> {
   const {
+    ca,
     followRedirects = true,
     headers = {},
     logger,
@@ -1103,6 +1151,7 @@ export async function httpDownload(
     try {
       // eslint-disable-next-line no-await-in-loop
       const result = await httpDownloadAttempt(url, tempPath, {
+        ca,
         followRedirects,
         headers,
         maxRedirects,
@@ -1296,6 +1345,7 @@ export async function httpRequest(
 ): Promise<HttpResponse> {
   const {
     body,
+    ca,
     followRedirects = true,
     headers = {},
     maxRedirects = 5,
@@ -1312,6 +1362,7 @@ export async function httpRequest(
       // eslint-disable-next-line no-await-in-loop
       return await httpRequestAttempt(url, {
         body,
+        ca,
         followRedirects,
         headers,
         maxRedirects,

test/unit/http-request.test.mts

@@ -1746,4 +1746,62 @@ abc123def456789012345678901234567890123456789012345678901234abcd
       }
     })
   })
+
+  describe('ca option', () => {
+    it('should accept ca option on httpRequest without error', async () => {
+      // ca is a no-op for HTTP (only applies to HTTPS), but should not throw.
+      const response = await httpRequest(`${httpBaseUrl}/text`, {
+        ca: ['-----BEGIN CERTIFICATE-----\ntest\n-----END CERTIFICATE-----'],
+      })
+
+      expect(response.status).toBe(200)
+      expect(response.text()).toBe('Plain text response')
+    })
+
+    it('should accept ca option on httpJson without error', async () => {
+      const data = await httpJson<{ message: string }>(`${httpBaseUrl}/json`, {
+        ca: ['-----BEGIN CERTIFICATE-----\ntest\n-----END CERTIFICATE-----'],
+      })
+
+      expect(data.message).toBe('Hello, World!')
+    })
+
+    it('should accept ca option on httpText without error', async () => {
+      const text = await httpText(`${httpBaseUrl}/text`, {
+        ca: ['-----BEGIN CERTIFICATE-----\ntest\n-----END CERTIFICATE-----'],
+      })
+
+      expect(text).toBe('Plain text response')
+    })
+
+    it('should accept ca option on httpDownload without error', async () => {
+      await runWithTempDir(async tempDir => {
+        const destPath = path.join(tempDir, 'ca-test.txt')
+        const result = await httpDownload(`${httpBaseUrl}/download`, destPath, {
+          ca: ['-----BEGIN CERTIFICATE-----\ntest\n-----END CERTIFICATE-----'],
+        })
+
+        expect(result.path).toBe(destPath)
+        expect(result.size).toBeGreaterThan(0)
+      })
+    })
+
+    it('should accept ca option on fetchChecksums without error', async () => {
+      const checksums = await fetchChecksums(`${httpBaseUrl}/checksums.txt`, {
+        ca: ['-----BEGIN CERTIFICATE-----\ntest\n-----END CERTIFICATE-----'],
+      })
+
+      expect(checksums['checksum-file']).toBeDefined()
+    })
+
+    it('should pass ca through redirects on httpRequest', async () => {
+      // ca should be preserved through redirect chains.
+      const response = await httpRequest(`${httpBaseUrl}/redirect`, {
+        ca: ['-----BEGIN CERTIFICATE-----\ntest\n-----END CERTIFICATE-----'],
+      })
+
+      expect(response.status).toBe(200)
+      expect(response.text()).toBe('Plain text response')
+    })
+  })
 })