TLS verification

Certificates are verified against the system's trusted roots, like any HTTPS client. A certificate that fails verification makes the request resolve with status: 0 and an x509 error in body.

Skipping verificationCopy Anchor Link

insecureSkipVerify: true accepts any certificate: self-signed, expired or for the wrong host. Use it for local testing and intercepting proxies, never against servers you don't control:

// Accept any certificate: self-signed, expired, wrong host. Testing only.
const insecure = new Session({ insecureSkipVerify: true });
const res = await insecure.get("https://self-signed.badssl.com/");
console.log(res.status); // 200 (without the option: status 0, "certificate signed by unknown authority")

Certificate pinningCopy Anchor Link

certificatePinningHosts only accepts specific certificates for a host. It maps a host name to a list of pins. A pin is the base64 SHA-256 hash of a certificate's public key (SPKI). The connection is accepted if any certificate in the server's chain matches any pin.

const session = new Session({
  certificatePinningHosts: {
    "httpbin.org": ["xVo7DFWLcuY2a0N/1xtOpTtrutF4Lr+7iR+oEciS3hI="],
  },
});

To get the pin of a server's leaf certificate with OpenSSL:

echo | openssl s_client -connect httpbin.org:443 -servername httpbin.org 2>/dev/null \
  | openssl x509 -pubkey -noout \
  | openssl pkey -pubin -outform der \
  | openssl dgst -sha256 -binary | openssl enc -base64

Or let the library tell you. A wrong pin fails with an error that lists every pin the server presented:

// A deliberately wrong pin makes the error list the pins the server presented.
const probe = new Session({
  certificatePinningHosts: {
    "httpbin.org": ["AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA="],
  },
});
const failed = await probe.get("https://httpbin.org/get");
console.log(failed.status, failed.body);
// 0 failed to do request: … bad ssl pin detected, found pins: [xVo7DF… brzvtC… …]

Leaf certificates change when they're renewed. Pinning an intermediate or root from the list is more durable; listing a backup pin avoids an outage on rotation.

Overriding the server name (SNI)Copy Anchor Link

serverNameOverwrite sets the TLS server name sent in the ClientHello, independently of the URL's host. It's mostly useful together with hostOverride when connecting to an IP address or a CDN edge directly. Certificate verification then checks the certificate against that name.

Session ticketsCopy Anchor Link

disableSessionTickets: true turns off TLS session ticket caching and resumption. It needs a tls-client build newer than the 1.16.0 release binaries; those silently ignore the option.