General improvements to HTTPS API

readme.md

@@ -40,6 +40,7 @@ For browser usage, we recommend [Ky](https://github.com/sindresorhus/ky) by the
 - [Errors with metadata](#errors)
 - [JSON mode](#json-mode)
 - [WHATWG URL support](#url)
+- [HTTPS](#https)
 - [Hooks](#hooks)
 - [Instances with custom defaults](#instances)
 - [Types](#types)
@@ -819,6 +820,92 @@ Type: `string`
 
 The IP address used to send the request from.
 
+### HTTPS
+
+##### ca
+
+Type: `string` | `string[]` | `Buffer` | `Buffer[]`
+
+Override the default CAs ([from Mozilla](https://ccadb-public.secure.force.com/mozilla/IncludedCACertificateReport))
+
+```js
+// Single CA
+got('https://example.com', {ca: fs.readFileSync('./my_ca.pem')});
+
+// Multiple CAs
+got('https://example.com', {
+	ca: [
+		fs.readFileSync('./my_ca1.pem'),
+		fs.readFileSync('./my_ca2.pem')
+	]
+});
+```
+
+##### key
+
+Type: `string` | `string[]` | `Buffer` | `Buffer[]` | `Object[]`
+
+Private keys in PEM format.\
+PEM allows the option of private keys being encrypted. Encrypted keys will be decrypted with `options.passphrase`.\
+Multiple keys with different passphrases can be provided as an array of `{pem: <string|Buffer>, passphrase: <string>}`
+
+##### cert
+
+Type: `string` | `string[]` | `Buffer` | `Buffer[]`
+
+Cert chains in PEM format.\
+One cert chain should be provided per private key (`options.key`).\
+When providing multiple cert chains, they do not have to be in the same order as their private keys in `options.key`.\
+If the intermediate certificates are not provided, the peer will not be able to validate the certificate, and the handshake will fail.
+
+##### passphrase
+
+Type: `string`
+
+The passphrase to decrypt the `key` (if different keys have different passphrases refer to `key` documentation).
+
+
+##### Examples for key, cert and passphrase
+
+```js
+// Single key with cert
+got('https://example.com', {
+	key: fs.readFileSync('./client_key.pem'),
+	cert: fs.readFileSync('./client_cert.pem'),
+});
+
+// Multiple keys with certs (out of order)
+got('https://example.com', {
+	key: [
+		fs.readFileSync('./client_key1.pem'),
+		fs.readFileSync('./client_key2.pem')
+	],
+	cert: [
+		fs.readFileSync('./client_cert2.pem'),
+		fs.readFileSync('./client_cert1.pem')
+	]
+});
+
+// Single key with passphrase
+got('https://example.com', {
+	key: fs.readFileSync('./client_key.pem'),
+	cert: fs.readFileSync('./client_cert.pem'),
+	passphrase: 'client_key_passphrase'
+});
+
+// Multiple keys with different passphrases
+got('https://example.com', {
+	key: [
+		{pem: fs.readFileSync('./client_key1.pem'), passphrase: 'passphrase1'},
+		{pem: fs.readFileSync('./client_key2.pem'), passphrase: 'passphrase2'},
+	],
+	cert: [
+		fs.readFileSync('./client_cert1.pem'),
+		fs.readFileSync('./client_cert2.pem')
+	]
+});
+```
+
 ##### rejectUnauthorized
 
 Type: `boolean`\
@@ -844,6 +931,31 @@ const got = require('got');
 })();
 ```
 
+##### checkServerIdentity
+
+Type: `Function`\
+Signature: `(hostname: string, certificate: DetailedPeerCertificate) => Error | undefined`\
+Default: `tls.checkServerIdentity` (from the `tls` module)
+
+This function enable a custom check of the certificate.\
+N.B. In order to have the function called the certificate must not be `expired`, `self-signed` or with an `untrusted-root`.\
+The function parameters are
+- `hostname`: the server hostname (used when connecting)
+- `certificate`: the server certificate
+
+The function must return `undefined` if the check succeeded or and `Error` if it failed.
+
+```js
+await got('https://example.com', {
+	checkServerIdentity: (hostname, certificate) => {
+		if (hostname === 'example.com')
+			return; // Certificate OK
+
+		return new Error('Invalid Hostname');
+	}
+});
+```
+
 #### Response
 
 The response object will typically be a [Node.js HTTP response stream](https://nodejs.org/api/http.html#http_class_http_incomingmessage), however, if returned from the cache it will be a [response-like object](https://github.com/lukechilds/responselike) which behaves in the same way.

source/core/index.ts

@@ -3,7 +3,7 @@ import {Duplex, Writable, Readable} from 'stream';
 import {ReadStream} from 'fs';
 import {URL, URLSearchParams} from 'url';
 import {Socket} from 'net';
-import {SecureContextOptions} from 'tls';
+import {SecureContextOptions, DetailedPeerCertificate} from 'tls';
 import http = require('http');
 import {ClientRequest, RequestOptions, IncomingMessage, ServerResponse, request as httpRequest} from 'http';
 import https = require('https');
@@ -142,6 +142,7 @@ export interface Options extends URLOptions, SecureContextOptions {
 	allowGetBody?: boolean;
 	lookup?: CacheableLookup['lookup'];
 	rejectUnauthorized?: boolean;
+	checkServerIdentity?: (hostname: string, certificate: DetailedPeerCertificate) => Error | void;
 	headers?: Headers;
 	methodRewriting?: boolean;
 

test/helpers/with-server.ts

@@ -18,7 +18,8 @@ const generateHook = ({install, options: testServerOptions}: {install?: boolean;
 	const server = await createTestServer(is.plainObject(testServerOptions) ? testServerOptions : {
 		bodyParser: {
 			type: () => false
-		}
+		},
+		certificate: 'example.com'
 	}) as ExtendedTestServer;
 
 	const options: InstanceDefaults = {

test/https.ts

@@ -1,27 +1,90 @@
 import test from 'ava';
 import got from '../source';
 import withServer from './helpers/with-server';
+import {PeerCertificate} from 'tls';
 
 test('https request without ca', withServer, async (t, server, got) => {
 	server.get('/', (_request, response) => {
 		response.end('ok');
 	});
 
-	t.truthy((await got({rejectUnauthorized: false})).body);
+	t.truthy((await got.secure({rejectUnauthorized: false})).body);
 });
 
 test('https request with ca', withServer, async (t, server, got) => {
 	server.get('/', (_request, response) => {
 		response.end('ok');
 	});
 
-	const {body} = await got({
+	const {body} = await got.secure({
 		ca: server.caCert,
-		headers: {host: 'sindresorhus.com'}
+		headers: {host: 'example.com'}
 	});
+
 	t.is(body, 'ok');
 });
 
+test('https request with checkServerIdentity OK', withServer, async (t, server, got) => {
+	server.get('/', (_request, response) => {
+		response.end('ok');
+	});
+
+	const {body} = await got.secure({
+		ca: server.caCert,
+		checkServerIdentity: (hostname: string, certificate: PeerCertificate) => {
+			t.is(hostname, 'example.com');
+			t.is(certificate.subject.CN, 'example.com');
+			t.is(certificate.issuer.CN, 'localhost');
+		},
+		headers: {host: 'example.com'}
+	});
+
+	t.is(body, 'ok');
+});
+
+test('https request with checkServerIdentity NOT OK', withServer, async (t, server, got) => {
+	server.get('/', (_request, response) => {
+		response.end('ok');
+	});
+
+	const promise = got.secure({
+		ca: server.caCert,
+		checkServerIdentity: (hostname: string, certificate: PeerCertificate) => {
+			t.is(hostname, 'example.com');
+			t.is(certificate.subject.CN, 'example.com');
+			t.is(certificate.issuer.CN, 'localhost');
+
+			return new Error('CUSTOM_ERROR');
+		},
+		headers: {host: 'example.com'}
+	});
+
+	await t.throwsAsync(
+		promise,
+		{
+			message: 'CUSTOM_ERROR'
+		}
+	);
+});
+
+test('https request with expired certificate', async t => {
+	await t.throwsAsync(
+		got('https://expired.badssl.com/'),
+		{
+			code: 'CERT_HAS_EXPIRED'
+		}
+	);
+});
+
+test('https request with wrong host', async t => {
+	await t.throwsAsync(
+		got('https://wrong.host.badssl.com/'),
+		{
+			code: 'ERR_TLS_CERT_ALTNAME_INVALID'
+		}
+	);
+});
+
 test('http2', async t => {
 	const promise = got('https://httpbin.org/anything', {
 		http2: true