1 |
|
2 |
|
3 |
|
4 |
|
5 |
|
6 | declare module 'https' {
|
7 | import { Duplex } from 'node:stream';
|
8 | import * as tls from 'node:tls';
|
9 | import * as http from 'node:http';
|
10 | import { URL } from 'node:url';
|
11 | type ServerOptions = tls.SecureContextOptions & tls.TlsOptions & http.ServerOptions;
|
12 | type RequestOptions = http.RequestOptions &
|
13 | tls.SecureContextOptions & {
|
14 | rejectUnauthorized?: boolean | undefined;
|
15 | servername?: string | undefined;
|
16 | };
|
17 | interface AgentOptions extends http.AgentOptions, tls.ConnectionOptions {
|
18 | rejectUnauthorized?: boolean | undefined;
|
19 | maxCachedSessions?: number | undefined;
|
20 | }
|
21 | |
22 |
|
23 |
|
24 |
|
25 | class Agent extends http.Agent {
|
26 | constructor(options?: AgentOptions);
|
27 | options: AgentOptions;
|
28 | }
|
29 | interface Server extends http.Server {}
|
30 | |
31 |
|
32 |
|
33 |
|
34 | class Server extends tls.Server {
|
35 | constructor(requestListener?: http.RequestListener);
|
36 | constructor(options: ServerOptions, requestListener?: http.RequestListener);
|
37 | addListener(event: string, listener: (...args: any[]) => void): this;
|
38 | addListener(event: 'keylog', listener: (line: Buffer, tlsSocket: tls.TLSSocket) => void): this;
|
39 | addListener(event: 'newSession', listener: (sessionId: Buffer, sessionData: Buffer, callback: (err: Error, resp: Buffer) => void) => void): this;
|
40 | addListener(event: 'OCSPRequest', listener: (certificate: Buffer, issuer: Buffer, callback: (err: Error | null, resp: Buffer) => void) => void): this;
|
41 | addListener(event: 'resumeSession', listener: (sessionId: Buffer, callback: (err: Error, sessionData: Buffer) => void) => void): this;
|
42 | addListener(event: 'secureConnection', listener: (tlsSocket: tls.TLSSocket) => void): this;
|
43 | addListener(event: 'tlsClientError', listener: (err: Error, tlsSocket: tls.TLSSocket) => void): this;
|
44 | addListener(event: 'close', listener: () => void): this;
|
45 | addListener(event: 'connection', listener: (socket: Duplex) => void): this;
|
46 | addListener(event: 'error', listener: (err: Error) => void): this;
|
47 | addListener(event: 'listening', listener: () => void): this;
|
48 | addListener(event: 'checkContinue', listener: http.RequestListener): this;
|
49 | addListener(event: 'checkExpectation', listener: http.RequestListener): this;
|
50 | addListener(event: 'clientError', listener: (err: Error, socket: Duplex) => void): this;
|
51 | addListener(event: 'connect', listener: (req: http.IncomingMessage, socket: Duplex, head: Buffer) => void): this;
|
52 | addListener(event: 'request', listener: http.RequestListener): this;
|
53 | addListener(event: 'upgrade', listener: (req: http.IncomingMessage, socket: Duplex, head: Buffer) => void): this;
|
54 | emit(event: string, ...args: any[]): boolean;
|
55 | emit(event: 'keylog', line: Buffer, tlsSocket: tls.TLSSocket): boolean;
|
56 | emit(event: 'newSession', sessionId: Buffer, sessionData: Buffer, callback: (err: Error, resp: Buffer) => void): boolean;
|
57 | emit(event: 'OCSPRequest', certificate: Buffer, issuer: Buffer, callback: (err: Error | null, resp: Buffer) => void): boolean;
|
58 | emit(event: 'resumeSession', sessionId: Buffer, callback: (err: Error, sessionData: Buffer) => void): boolean;
|
59 | emit(event: 'secureConnection', tlsSocket: tls.TLSSocket): boolean;
|
60 | emit(event: 'tlsClientError', err: Error, tlsSocket: tls.TLSSocket): boolean;
|
61 | emit(event: 'close'): boolean;
|
62 | emit(event: 'connection', socket: Duplex): boolean;
|
63 | emit(event: 'error', err: Error): boolean;
|
64 | emit(event: 'listening'): boolean;
|
65 | emit(event: 'checkContinue', req: http.IncomingMessage, res: http.ServerResponse): boolean;
|
66 | emit(event: 'checkExpectation', req: http.IncomingMessage, res: http.ServerResponse): boolean;
|
67 | emit(event: 'clientError', err: Error, socket: Duplex): boolean;
|
68 | emit(event: 'connect', req: http.IncomingMessage, socket: Duplex, head: Buffer): boolean;
|
69 | emit(event: 'request', req: http.IncomingMessage, res: http.ServerResponse): boolean;
|
70 | emit(event: 'upgrade', req: http.IncomingMessage, socket: Duplex, head: Buffer): boolean;
|
71 | on(event: string, listener: (...args: any[]) => void): this;
|
72 | on(event: 'keylog', listener: (line: Buffer, tlsSocket: tls.TLSSocket) => void): this;
|
73 | on(event: 'newSession', listener: (sessionId: Buffer, sessionData: Buffer, callback: (err: Error, resp: Buffer) => void) => void): this;
|
74 | on(event: 'OCSPRequest', listener: (certificate: Buffer, issuer: Buffer, callback: (err: Error | null, resp: Buffer) => void) => void): this;
|
75 | on(event: 'resumeSession', listener: (sessionId: Buffer, callback: (err: Error, sessionData: Buffer) => void) => void): this;
|
76 | on(event: 'secureConnection', listener: (tlsSocket: tls.TLSSocket) => void): this;
|
77 | on(event: 'tlsClientError', listener: (err: Error, tlsSocket: tls.TLSSocket) => void): this;
|
78 | on(event: 'close', listener: () => void): this;
|
79 | on(event: 'connection', listener: (socket: Duplex) => void): this;
|
80 | on(event: 'error', listener: (err: Error) => void): this;
|
81 | on(event: 'listening', listener: () => void): this;
|
82 | on(event: 'checkContinue', listener: http.RequestListener): this;
|
83 | on(event: 'checkExpectation', listener: http.RequestListener): this;
|
84 | on(event: 'clientError', listener: (err: Error, socket: Duplex) => void): this;
|
85 | on(event: 'connect', listener: (req: http.IncomingMessage, socket: Duplex, head: Buffer) => void): this;
|
86 | on(event: 'request', listener: http.RequestListener): this;
|
87 | on(event: 'upgrade', listener: (req: http.IncomingMessage, socket: Duplex, head: Buffer) => void): this;
|
88 | once(event: string, listener: (...args: any[]) => void): this;
|
89 | once(event: 'keylog', listener: (line: Buffer, tlsSocket: tls.TLSSocket) => void): this;
|
90 | once(event: 'newSession', listener: (sessionId: Buffer, sessionData: Buffer, callback: (err: Error, resp: Buffer) => void) => void): this;
|
91 | once(event: 'OCSPRequest', listener: (certificate: Buffer, issuer: Buffer, callback: (err: Error | null, resp: Buffer) => void) => void): this;
|
92 | once(event: 'resumeSession', listener: (sessionId: Buffer, callback: (err: Error, sessionData: Buffer) => void) => void): this;
|
93 | once(event: 'secureConnection', listener: (tlsSocket: tls.TLSSocket) => void): this;
|
94 | once(event: 'tlsClientError', listener: (err: Error, tlsSocket: tls.TLSSocket) => void): this;
|
95 | once(event: 'close', listener: () => void): this;
|
96 | once(event: 'connection', listener: (socket: Duplex) => void): this;
|
97 | once(event: 'error', listener: (err: Error) => void): this;
|
98 | once(event: 'listening', listener: () => void): this;
|
99 | once(event: 'checkContinue', listener: http.RequestListener): this;
|
100 | once(event: 'checkExpectation', listener: http.RequestListener): this;
|
101 | once(event: 'clientError', listener: (err: Error, socket: Duplex) => void): this;
|
102 | once(event: 'connect', listener: (req: http.IncomingMessage, socket: Duplex, head: Buffer) => void): this;
|
103 | once(event: 'request', listener: http.RequestListener): this;
|
104 | once(event: 'upgrade', listener: (req: http.IncomingMessage, socket: Duplex, head: Buffer) => void): this;
|
105 | prependListener(event: string, listener: (...args: any[]) => void): this;
|
106 | prependListener(event: 'keylog', listener: (line: Buffer, tlsSocket: tls.TLSSocket) => void): this;
|
107 | prependListener(event: 'newSession', listener: (sessionId: Buffer, sessionData: Buffer, callback: (err: Error, resp: Buffer) => void) => void): this;
|
108 | prependListener(event: 'OCSPRequest', listener: (certificate: Buffer, issuer: Buffer, callback: (err: Error | null, resp: Buffer) => void) => void): this;
|
109 | prependListener(event: 'resumeSession', listener: (sessionId: Buffer, callback: (err: Error, sessionData: Buffer) => void) => void): this;
|
110 | prependListener(event: 'secureConnection', listener: (tlsSocket: tls.TLSSocket) => void): this;
|
111 | prependListener(event: 'tlsClientError', listener: (err: Error, tlsSocket: tls.TLSSocket) => void): this;
|
112 | prependListener(event: 'close', listener: () => void): this;
|
113 | prependListener(event: 'connection', listener: (socket: Duplex) => void): this;
|
114 | prependListener(event: 'error', listener: (err: Error) => void): this;
|
115 | prependListener(event: 'listening', listener: () => void): this;
|
116 | prependListener(event: 'checkContinue', listener: http.RequestListener): this;
|
117 | prependListener(event: 'checkExpectation', listener: http.RequestListener): this;
|
118 | prependListener(event: 'clientError', listener: (err: Error, socket: Duplex) => void): this;
|
119 | prependListener(event: 'connect', listener: (req: http.IncomingMessage, socket: Duplex, head: Buffer) => void): this;
|
120 | prependListener(event: 'request', listener: http.RequestListener): this;
|
121 | prependListener(event: 'upgrade', listener: (req: http.IncomingMessage, socket: Duplex, head: Buffer) => void): this;
|
122 | prependOnceListener(event: string, listener: (...args: any[]) => void): this;
|
123 | prependOnceListener(event: 'keylog', listener: (line: Buffer, tlsSocket: tls.TLSSocket) => void): this;
|
124 | prependOnceListener(event: 'newSession', listener: (sessionId: Buffer, sessionData: Buffer, callback: (err: Error, resp: Buffer) => void) => void): this;
|
125 | prependOnceListener(event: 'OCSPRequest', listener: (certificate: Buffer, issuer: Buffer, callback: (err: Error | null, resp: Buffer) => void) => void): this;
|
126 | prependOnceListener(event: 'resumeSession', listener: (sessionId: Buffer, callback: (err: Error, sessionData: Buffer) => void) => void): this;
|
127 | prependOnceListener(event: 'secureConnection', listener: (tlsSocket: tls.TLSSocket) => void): this;
|
128 | prependOnceListener(event: 'tlsClientError', listener: (err: Error, tlsSocket: tls.TLSSocket) => void): this;
|
129 | prependOnceListener(event: 'close', listener: () => void): this;
|
130 | prependOnceListener(event: 'connection', listener: (socket: Duplex) => void): this;
|
131 | prependOnceListener(event: 'error', listener: (err: Error) => void): this;
|
132 | prependOnceListener(event: 'listening', listener: () => void): this;
|
133 | prependOnceListener(event: 'checkContinue', listener: http.RequestListener): this;
|
134 | prependOnceListener(event: 'checkExpectation', listener: http.RequestListener): this;
|
135 | prependOnceListener(event: 'clientError', listener: (err: Error, socket: Duplex) => void): this;
|
136 | prependOnceListener(event: 'connect', listener: (req: http.IncomingMessage, socket: Duplex, head: Buffer) => void): this;
|
137 | prependOnceListener(event: 'request', listener: http.RequestListener): this;
|
138 | prependOnceListener(event: 'upgrade', listener: (req: http.IncomingMessage, socket: Duplex, head: Buffer) => void): this;
|
139 | }
|
140 | /**
|
141 | * ```js
|
142 | * // curl -k https://localhost:8000/
|
143 | * const https = require('https');
|
144 | * const fs = require('fs');
|
145 | *
|
146 | * const options = {
|
147 | * key: fs.readFileSync('test/fixtures/keys/agent2-key.pem'),
|
148 | * cert: fs.readFileSync('test/fixtures/keys/agent2-cert.pem')
|
149 | * };
|
150 | *
|
151 | * https.createServer(options, (req, res) => {
|
152 | * res.writeHead(200);
|
153 | * res.end('hello world\n');
|
154 | * }).listen(8000);
|
155 | * ```
|
156 | *
|
157 | * Or
|
158 | *
|
159 | * ```js
|
160 | * const https = require('https');
|
161 | * const fs = require('fs');
|
162 | *
|
163 | * const options = {
|
164 | * pfx: fs.readFileSync('test/fixtures/test_cert.pfx'),
|
165 | * passphrase: 'sample'
|
166 | * };
|
167 | *
|
168 | * https.createServer(options, (req, res) => {
|
169 | * res.writeHead(200);
|
170 | * res.end('hello world\n');
|
171 | * }).listen(8000);
|
172 | * ```
|
173 | * @since v0.3.4
|
174 | * @param options Accepts `options` from `createServer`, `createSecureContext` and `createServer`.
|
175 | * @param requestListener A listener to be added to the `'request'` event.
|
176 | */
|
177 | function createServer(requestListener?: http.RequestListener): Server;
|
178 | function createServer(options: ServerOptions, requestListener?: http.RequestListener): Server;
|
179 | /**
|
180 | * Makes a request to a secure web server.
|
181 | *
|
182 | * The following additional `options` from `tls.connect()` are also accepted:`ca`, `cert`, `ciphers`, `clientCertEngine`, `crl`, `dhparam`, `ecdhCurve`,`honorCipherOrder`, `key`, `passphrase`,
|
183 | * `pfx`, `rejectUnauthorized`,`secureOptions`, `secureProtocol`, `servername`, `sessionIdContext`,`highWaterMark`.
|
184 | *
|
185 | * `options` can be an object, a string, or a `URL` object. If `options` is a
|
186 | * string, it is automatically parsed with `new URL()`. If it is a `URL` object, it will be automatically converted to an ordinary `options` object.
|
187 | *
|
188 | * `https.request()` returns an instance of the `http.ClientRequest` class. The `ClientRequest` instance is a writable stream. If one needs to
|
189 | * upload a file with a POST request, then write to the `ClientRequest` object.
|
190 | *
|
191 | * ```js
|
192 | * const https = require('https');
|
193 | *
|
194 | * const options = {
|
195 | * hostname: 'encrypted.google.com',
|
196 | * port: 443,
|
197 | * path: '/',
|
198 | * method: 'GET'
|
199 | * };
|
200 | *
|
201 | * const req = https.request(options, (res) => {
|
202 | * console.log('statusCode:', res.statusCode);
|
203 | * console.log('headers:', res.headers);
|
204 | *
|
205 | * res.on('data', (d) => {
|
206 | * process.stdout.write(d);
|
207 | * });
|
208 | * });
|
209 | *
|
210 | * req.on('error', (e) => {
|
211 | * console.error(e);
|
212 | * });
|
213 | * req.end();
|
214 | * ```
|
215 | *
|
216 | * Example using options from `tls.connect()`:
|
217 | *
|
218 | * ```js
|
219 | * const options = {
|
220 | * hostname: 'encrypted.google.com',
|
221 | * port: 443,
|
222 | * path: '/',
|
223 | * method: 'GET',
|
224 | * key: fs.readFileSync('test/fixtures/keys/agent2-key.pem'),
|
225 | * cert: fs.readFileSync('test/fixtures/keys/agent2-cert.pem')
|
226 | * };
|
227 | * options.agent = new https.Agent(options);
|
228 | *
|
229 | * const req = https.request(options, (res) => {
|
230 | *
|
231 | * });
|
232 | * ```
|
233 | *
|
234 | * Alternatively, opt out of connection pooling by not using an `Agent`.
|
235 | *
|
236 | * ```js
|
237 | * const options = {
|
238 | * hostname: 'encrypted.google.com',
|
239 | * port: 443,
|
240 | * path: '/',
|
241 | * method: 'GET',
|
242 | * key: fs.readFileSync('test/fixtures/keys/agent2-key.pem'),
|
243 | * cert: fs.readFileSync('test/fixtures/keys/agent2-cert.pem'),
|
244 | * agent: false
|
245 | * };
|
246 | *
|
247 | * const req = https.request(options, (res) => {
|
248 | *
|
249 | * });
|
250 | * ```
|
251 | *
|
252 | * Example using a `URL` as `options`:
|
253 | *
|
254 | * ```js
|
255 | * const options = new URL('https://abc:xyz@example.com');
|
256 | *
|
257 | * const req = https.request(options, (res) => {
|
258 | *
|
259 | * });
|
260 | * ```
|
261 | *
|
262 | * Example pinning on certificate fingerprint, or the public key (similar to`pin-sha256`):
|
263 | *
|
264 | * ```js
|
265 | * const tls = require('tls');
|
266 | * const https = require('https');
|
267 | * const crypto = require('crypto');
|
268 | *
|
269 | * function sha256(s) {
|
270 | * return crypto.createHash('sha256').update(s).digest('base64');
|
271 | * }
|
272 | * const options = {
|
273 | * hostname: 'github.com',
|
274 | * port: 443,
|
275 | * path: '/',
|
276 | * method: 'GET',
|
277 | * checkServerIdentity: function(host, cert) {
|
278 | *
|
279 | * const err = tls.checkServerIdentity(host, cert);
|
280 | * if (err) {
|
281 | * return err;
|
282 | * }
|
283 | *
|
284 | *
|
285 | * const pubkey256 = 'pL1+qb9HTMRZJmuC/bB/ZI9d302BYrrqiVuRyW+DGrU=';
|
286 | * if (sha256(cert.pubkey) !== pubkey256) {
|
287 | * const msg = 'Certificate verification error: ' +
|
288 | * `The public key of '${cert.subject.CN}' ` +
|
289 | * 'does not match our pinned fingerprint';
|
290 | * return new Error(msg);
|
291 | * }
|
292 | *
|
293 | *
|
294 | * const cert256 = '25:FE:39:32:D9:63:8C:8A:FC:A1:9A:29:87:' +
|
295 | * 'D8:3E:4C:1D:98:DB:71:E4:1A:48:03:98:EA:22:6A:BD:8B:93:16';
|
296 | * if (cert.fingerprint256 !== cert256) {
|
297 | * const msg = 'Certificate verification error: ' +
|
298 | * `The certificate of '${cert.subject.CN}' ` +
|
299 | * 'does not match our pinned fingerprint';
|
300 | * return new Error(msg);
|
301 | * }
|
302 | *
|
303 | *
|
304 | *
|
305 | *
|
306 | *
|
307 | *
|
308 | * do {
|
309 | * console.log('Subject Common Name:', cert.subject.CN);
|
310 | * console.log(' Certificate SHA256 fingerprint:', cert.fingerprint256);
|
311 | *
|
312 | * hash = crypto.createHash('sha256');
|
313 | * console.log(' Public key ping-sha256:', sha256(cert.pubkey));
|
314 | *
|
315 | * lastprint256 = cert.fingerprint256;
|
316 | * cert = cert.issuerCertificate;
|
317 | * } while (cert.fingerprint256 !== lastprint256);
|
318 | *
|
319 | * },
|
320 | * };
|
321 | *
|
322 | * options.agent = new https.Agent(options);
|
323 | * const req = https.request(options, (res) => {
|
324 | * console.log('All OK. Server matched our pinned cert or public key');
|
325 | * console.log('statusCode:', res.statusCode);
|
326 | *
|
327 | * console.log('headers:', res.headers['public-key-pins']);
|
328 | *
|
329 | * res.on('data', (d) => {});
|
330 | * });
|
331 | *
|
332 | * req.on('error', (e) => {
|
333 | * console.error(e.message);
|
334 | * });
|
335 | * req.end();
|
336 | * ```
|
337 | *
|
338 | * Outputs for example:
|
339 | *
|
340 | * ```text
|
341 | * Subject Common Name: github.com
|
342 | * Certificate SHA256 fingerprint: 25:FE:39:32:D9:63:8C:8A:FC:A1:9A:29:87:D8:3E:4C:1D:98:DB:71:E4:1A:48:03:98:EA:22:6A:BD:8B:93:16
|
343 | * Public key ping-sha256: pL1+qb9HTMRZJmuC/bB/ZI9d302BYrrqiVuRyW+DGrU=
|
344 | * Subject Common Name: DigiCert SHA2 Extended Validation Server CA
|
345 | * Certificate SHA256 fingerprint: 40:3E:06:2A:26:53:05:91:13:28:5B:AF:80:A0:D4:AE:42:2C:84:8C:9F:78:FA:D0:1F:C9:4B:C5:B8:7F:EF:1A
|
346 | * Public key ping-sha256: RRM1dGqnDFsCJXBTHky16vi1obOlCgFFn/yOhI/y+ho=
|
347 | * Subject Common Name: DigiCert High Assurance EV Root CA
|
348 | * Certificate SHA256 fingerprint: 74:31:E5:F4:C3:C1:CE:46:90:77:4F:0B:61:E0:54:40:88:3B:A9:A0:1E:D0:0B:A6:AB:D7:80:6E:D3:B1:18:CF
|
349 | * Public key ping-sha256: WoiWRyIOVNa9ihaBciRSC7XHjliYS9VwUGOIud4PB18=
|
350 | * All OK. Server matched our pinned cert or public key
|
351 | * statusCode: 200
|
352 | * headers: max-age=0; pin-sha256="WoiWRyIOVNa9ihaBciRSC7XHjliYS9VwUGOIud4PB18="; pin-sha256="RRM1dGqnDFsCJXBTHky16vi1obOlCgFFn/yOhI/y+ho=";
|
353 | * pin-sha256="k2v657xBsOVe1PQRwOsHsw3bsGT2VzIqz5K+59sNQws="; pin-sha256="K87oWBWM9UZfyddvDfoxL+8lpNyoUB2ptGtn0fv6G2Q="; pin-sha256="IQBnNBEiFuhj+8x6X8XLgh01V9Ic5/V3IRQLNFFc7v4=";
|
354 | * pin-sha256="iie1VXtL7HzAMF+/PVPR9xzT80kQxdZeJ+zduCB3uj0="; pin-sha256="LvRiGEjRqfzurezaWuj8Wie2gyHMrW5Q06LspMnox7A="; includeSubDomains
|
355 | * ```
|
356 | * @since v0.3.6
|
357 | * @param options Accepts all `options` from `request`, with some differences in default values:
|
358 | */
|
359 | function request(options: RequestOptions | string | URL, callback?: (res: http.IncomingMessage) => void): http.ClientRequest;
|
360 | function request(url: string | URL, options: RequestOptions, callback?: (res: http.IncomingMessage) => void): http.ClientRequest;
|
361 | /**
|
362 | * Like `http.get()` but for HTTPS.
|
363 | *
|
364 | * `options` can be an object, a string, or a `URL` object. If `options` is a
|
365 | * string, it is automatically parsed with `new URL()`. If it is a `URL` object, it will be automatically converted to an ordinary `options` object.
|
366 | *
|
367 | * ```js
|
368 | * const https = require('https');
|
369 | *
|
370 | * https.get('https://encrypted.google.com/', (res) => {
|
371 | * console.log('statusCode:', res.statusCode);
|
372 | * console.log('headers:', res.headers);
|
373 | *
|
374 | * res.on('data', (d) => {
|
375 | * process.stdout.write(d);
|
376 | * });
|
377 | *
|
378 | * }).on('error', (e) => {
|
379 | * console.error(e);
|
380 | * });
|
381 | * ```
|
382 | * @since v0.3.6
|
383 | * @param options Accepts the same `options` as {@link request}, with the `method` always set to `GET`.
|
384 | */
|
385 | function get(options: RequestOptions | string | URL, callback?: (res: http.IncomingMessage) => void): http.ClientRequest;
|
386 | function get(url: string | URL, options: RequestOptions, callback?: (res: http.IncomingMessage) => void): http.ClientRequest;
|
387 | let globalAgent: Agent;
|
388 | }
|
389 | declare module 'node:https' {
|
390 | export * from 'https';
|
391 | }
|
392 |
|
\ | No newline at end of file |