https.d.ts (24419B)
1 /** 2 * HTTPS is the HTTP protocol over TLS/SSL. In Node.js this is implemented as a 3 * separate module. 4 * @see [source](https://github.com/nodejs/node/blob/v16.9.0/lib/https.js) 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< 12 Request extends typeof http.IncomingMessage = typeof http.IncomingMessage, 13 Response extends typeof http.ServerResponse<InstanceType<Request>> = typeof http.ServerResponse, 14 > = tls.SecureContextOptions & tls.TlsOptions & http.ServerOptions<Request, Response>; 15 type RequestOptions = 16 & http.RequestOptions 17 & tls.SecureContextOptions 18 & { 19 checkServerIdentity?: typeof tls.checkServerIdentity | undefined; 20 rejectUnauthorized?: boolean | undefined; // Defaults to true 21 servername?: string | undefined; // SNI TLS Extension 22 }; 23 interface AgentOptions extends http.AgentOptions, tls.ConnectionOptions { 24 rejectUnauthorized?: boolean | undefined; 25 maxCachedSessions?: number | undefined; 26 } 27 /** 28 * An `Agent` object for HTTPS similar to `http.Agent`. See {@link request} for more information. 29 * @since v0.4.5 30 */ 31 class Agent extends http.Agent { 32 constructor(options?: AgentOptions); 33 options: AgentOptions; 34 } 35 interface Server< 36 Request extends typeof http.IncomingMessage = typeof http.IncomingMessage, 37 Response extends typeof http.ServerResponse<InstanceType<Request>> = typeof http.ServerResponse, 38 > extends http.Server<Request, Response> {} 39 /** 40 * See `http.Server` for more information. 41 * @since v0.3.4 42 */ 43 class Server< 44 Request extends typeof http.IncomingMessage = typeof http.IncomingMessage, 45 Response extends typeof http.ServerResponse<InstanceType<Request>> = typeof http.ServerResponse, 46 > extends tls.Server { 47 constructor(requestListener?: http.RequestListener<Request, Response>); 48 constructor( 49 options: ServerOptions<Request, Response>, 50 requestListener?: http.RequestListener<Request, Response>, 51 ); 52 addListener(event: string, listener: (...args: any[]) => void): this; 53 addListener(event: "keylog", listener: (line: Buffer, tlsSocket: tls.TLSSocket) => void): this; 54 addListener( 55 event: "newSession", 56 listener: (sessionId: Buffer, sessionData: Buffer, callback: (err: Error, resp: Buffer) => void) => void, 57 ): this; 58 addListener( 59 event: "OCSPRequest", 60 listener: ( 61 certificate: Buffer, 62 issuer: Buffer, 63 callback: (err: Error | null, resp: Buffer) => void, 64 ) => void, 65 ): this; 66 addListener( 67 event: "resumeSession", 68 listener: (sessionId: Buffer, callback: (err: Error, sessionData: Buffer) => void) => void, 69 ): this; 70 addListener(event: "secureConnection", listener: (tlsSocket: tls.TLSSocket) => void): this; 71 addListener(event: "tlsClientError", listener: (err: Error, tlsSocket: tls.TLSSocket) => void): this; 72 addListener(event: "close", listener: () => void): this; 73 addListener(event: "connection", listener: (socket: Duplex) => void): this; 74 addListener(event: "error", listener: (err: Error) => void): this; 75 addListener(event: "listening", listener: () => void): this; 76 addListener(event: "checkContinue", listener: http.RequestListener<Request, Response>): this; 77 addListener(event: "checkExpectation", listener: http.RequestListener<Request, Response>): this; 78 addListener(event: "clientError", listener: (err: Error, socket: Duplex) => void): this; 79 addListener( 80 event: "connect", 81 listener: (req: InstanceType<Request>, socket: Duplex, head: Buffer) => void, 82 ): this; 83 addListener(event: "request", listener: http.RequestListener<Request, Response>): this; 84 addListener( 85 event: "upgrade", 86 listener: (req: InstanceType<Request>, socket: Duplex, head: Buffer) => void, 87 ): this; 88 emit(event: string, ...args: any[]): boolean; 89 emit(event: "keylog", line: Buffer, tlsSocket: tls.TLSSocket): boolean; 90 emit( 91 event: "newSession", 92 sessionId: Buffer, 93 sessionData: Buffer, 94 callback: (err: Error, resp: Buffer) => void, 95 ): boolean; 96 emit( 97 event: "OCSPRequest", 98 certificate: Buffer, 99 issuer: Buffer, 100 callback: (err: Error | null, resp: Buffer) => void, 101 ): boolean; 102 emit(event: "resumeSession", sessionId: Buffer, callback: (err: Error, sessionData: Buffer) => void): boolean; 103 emit(event: "secureConnection", tlsSocket: tls.TLSSocket): boolean; 104 emit(event: "tlsClientError", err: Error, tlsSocket: tls.TLSSocket): boolean; 105 emit(event: "close"): boolean; 106 emit(event: "connection", socket: Duplex): boolean; 107 emit(event: "error", err: Error): boolean; 108 emit(event: "listening"): boolean; 109 emit( 110 event: "checkContinue", 111 req: InstanceType<Request>, 112 res: InstanceType<Response>, 113 ): boolean; 114 emit( 115 event: "checkExpectation", 116 req: InstanceType<Request>, 117 res: InstanceType<Response>, 118 ): boolean; 119 emit(event: "clientError", err: Error, socket: Duplex): boolean; 120 emit(event: "connect", req: InstanceType<Request>, socket: Duplex, head: Buffer): boolean; 121 emit( 122 event: "request", 123 req: InstanceType<Request>, 124 res: InstanceType<Response>, 125 ): boolean; 126 emit(event: "upgrade", req: InstanceType<Request>, socket: Duplex, head: Buffer): boolean; 127 on(event: string, listener: (...args: any[]) => void): this; 128 on(event: "keylog", listener: (line: Buffer, tlsSocket: tls.TLSSocket) => void): this; 129 on( 130 event: "newSession", 131 listener: (sessionId: Buffer, sessionData: Buffer, callback: (err: Error, resp: Buffer) => void) => void, 132 ): this; 133 on( 134 event: "OCSPRequest", 135 listener: ( 136 certificate: Buffer, 137 issuer: Buffer, 138 callback: (err: Error | null, resp: Buffer) => void, 139 ) => void, 140 ): this; 141 on( 142 event: "resumeSession", 143 listener: (sessionId: Buffer, callback: (err: Error, sessionData: Buffer) => void) => void, 144 ): this; 145 on(event: "secureConnection", listener: (tlsSocket: tls.TLSSocket) => void): this; 146 on(event: "tlsClientError", listener: (err: Error, tlsSocket: tls.TLSSocket) => void): this; 147 on(event: "close", listener: () => void): this; 148 on(event: "connection", listener: (socket: Duplex) => void): this; 149 on(event: "error", listener: (err: Error) => void): this; 150 on(event: "listening", listener: () => void): this; 151 on(event: "checkContinue", listener: http.RequestListener<Request, Response>): this; 152 on(event: "checkExpectation", listener: http.RequestListener<Request, Response>): this; 153 on(event: "clientError", listener: (err: Error, socket: Duplex) => void): this; 154 on(event: "connect", listener: (req: InstanceType<Request>, socket: Duplex, head: Buffer) => void): this; 155 on(event: "request", listener: http.RequestListener<Request, Response>): this; 156 on(event: "upgrade", listener: (req: InstanceType<Request>, socket: Duplex, head: Buffer) => void): this; 157 once(event: string, listener: (...args: any[]) => void): this; 158 once(event: "keylog", listener: (line: Buffer, tlsSocket: tls.TLSSocket) => void): this; 159 once( 160 event: "newSession", 161 listener: (sessionId: Buffer, sessionData: Buffer, callback: (err: Error, resp: Buffer) => void) => void, 162 ): this; 163 once( 164 event: "OCSPRequest", 165 listener: ( 166 certificate: Buffer, 167 issuer: Buffer, 168 callback: (err: Error | null, resp: Buffer) => void, 169 ) => void, 170 ): this; 171 once( 172 event: "resumeSession", 173 listener: (sessionId: Buffer, callback: (err: Error, sessionData: Buffer) => void) => void, 174 ): this; 175 once(event: "secureConnection", listener: (tlsSocket: tls.TLSSocket) => void): this; 176 once(event: "tlsClientError", listener: (err: Error, tlsSocket: tls.TLSSocket) => void): this; 177 once(event: "close", listener: () => void): this; 178 once(event: "connection", listener: (socket: Duplex) => void): this; 179 once(event: "error", listener: (err: Error) => void): this; 180 once(event: "listening", listener: () => void): this; 181 once(event: "checkContinue", listener: http.RequestListener<Request, Response>): this; 182 once(event: "checkExpectation", listener: http.RequestListener<Request, Response>): this; 183 once(event: "clientError", listener: (err: Error, socket: Duplex) => void): this; 184 once(event: "connect", listener: (req: InstanceType<Request>, socket: Duplex, head: Buffer) => void): this; 185 once(event: "request", listener: http.RequestListener<Request, Response>): this; 186 once(event: "upgrade", listener: (req: InstanceType<Request>, socket: Duplex, head: Buffer) => void): this; 187 prependListener(event: string, listener: (...args: any[]) => void): this; 188 prependListener(event: "keylog", listener: (line: Buffer, tlsSocket: tls.TLSSocket) => void): this; 189 prependListener( 190 event: "newSession", 191 listener: (sessionId: Buffer, sessionData: Buffer, callback: (err: Error, resp: Buffer) => void) => void, 192 ): this; 193 prependListener( 194 event: "OCSPRequest", 195 listener: ( 196 certificate: Buffer, 197 issuer: Buffer, 198 callback: (err: Error | null, resp: Buffer) => void, 199 ) => void, 200 ): this; 201 prependListener( 202 event: "resumeSession", 203 listener: (sessionId: Buffer, callback: (err: Error, sessionData: Buffer) => void) => void, 204 ): this; 205 prependListener(event: "secureConnection", listener: (tlsSocket: tls.TLSSocket) => void): this; 206 prependListener(event: "tlsClientError", listener: (err: Error, tlsSocket: tls.TLSSocket) => void): this; 207 prependListener(event: "close", listener: () => void): this; 208 prependListener(event: "connection", listener: (socket: Duplex) => void): this; 209 prependListener(event: "error", listener: (err: Error) => void): this; 210 prependListener(event: "listening", listener: () => void): this; 211 prependListener(event: "checkContinue", listener: http.RequestListener<Request, Response>): this; 212 prependListener(event: "checkExpectation", listener: http.RequestListener<Request, Response>): this; 213 prependListener(event: "clientError", listener: (err: Error, socket: Duplex) => void): this; 214 prependListener( 215 event: "connect", 216 listener: (req: InstanceType<Request>, socket: Duplex, head: Buffer) => void, 217 ): this; 218 prependListener(event: "request", listener: http.RequestListener<Request, Response>): this; 219 prependListener( 220 event: "upgrade", 221 listener: (req: InstanceType<Request>, socket: Duplex, head: Buffer) => void, 222 ): this; 223 prependOnceListener(event: string, listener: (...args: any[]) => void): this; 224 prependOnceListener(event: "keylog", listener: (line: Buffer, tlsSocket: tls.TLSSocket) => void): this; 225 prependOnceListener( 226 event: "newSession", 227 listener: (sessionId: Buffer, sessionData: Buffer, callback: (err: Error, resp: Buffer) => void) => void, 228 ): this; 229 prependOnceListener( 230 event: "OCSPRequest", 231 listener: ( 232 certificate: Buffer, 233 issuer: Buffer, 234 callback: (err: Error | null, resp: Buffer) => void, 235 ) => void, 236 ): this; 237 prependOnceListener( 238 event: "resumeSession", 239 listener: (sessionId: Buffer, callback: (err: Error, sessionData: Buffer) => void) => void, 240 ): this; 241 prependOnceListener(event: "secureConnection", listener: (tlsSocket: tls.TLSSocket) => void): this; 242 prependOnceListener(event: "tlsClientError", listener: (err: Error, tlsSocket: tls.TLSSocket) => void): this; 243 prependOnceListener(event: "close", listener: () => void): this; 244 prependOnceListener(event: "connection", listener: (socket: Duplex) => void): this; 245 prependOnceListener(event: "error", listener: (err: Error) => void): this; 246 prependOnceListener(event: "listening", listener: () => void): this; 247 prependOnceListener(event: "checkContinue", listener: http.RequestListener<Request, Response>): this; 248 prependOnceListener(event: "checkExpectation", listener: http.RequestListener<Request, Response>): this; 249 prependOnceListener(event: "clientError", listener: (err: Error, socket: Duplex) => void): this; 250 prependOnceListener( 251 event: "connect", 252 listener: (req: InstanceType<Request>, socket: Duplex, head: Buffer) => void, 253 ): this; 254 prependOnceListener(event: "request", listener: http.RequestListener<Request, Response>): this; 255 prependOnceListener( 256 event: "upgrade", 257 listener: (req: InstanceType<Request>, socket: Duplex, head: Buffer) => void, 258 ): this; 259 } 260 /** 261 * ```js 262 * // curl -k https://localhost:8000/ 263 * import https from 'node:https'; 264 * import fs from 'node:fs'; 265 * 266 * const options = { 267 * key: fs.readFileSync('test/fixtures/keys/agent2-key.pem'), 268 * cert: fs.readFileSync('test/fixtures/keys/agent2-cert.pem') 269 * }; 270 * 271 * https.createServer(options, (req, res) => { 272 * res.writeHead(200); 273 * res.end('hello world\n'); 274 * }).listen(8000); 275 * ``` 276 * 277 * Or 278 * 279 * ```js 280 * import https from 'node:https'; 281 * import fs from 'node:fs'; 282 * 283 * const options = { 284 * pfx: fs.readFileSync('test/fixtures/test_cert.pfx'), 285 * passphrase: 'sample' 286 * }; 287 * 288 * https.createServer(options, (req, res) => { 289 * res.writeHead(200); 290 * res.end('hello world\n'); 291 * }).listen(8000); 292 * ``` 293 * @since v0.3.4 294 * @param options Accepts `options` from `createServer`, `createSecureContext` and `createServer`. 295 * @param requestListener A listener to be added to the `'request'` event. 296 */ 297 function createServer< 298 Request extends typeof http.IncomingMessage = typeof http.IncomingMessage, 299 Response extends typeof http.ServerResponse<InstanceType<Request>> = typeof http.ServerResponse, 300 >(requestListener?: http.RequestListener<Request, Response>): Server<Request, Response>; 301 function createServer< 302 Request extends typeof http.IncomingMessage = typeof http.IncomingMessage, 303 Response extends typeof http.ServerResponse<InstanceType<Request>> = typeof http.ServerResponse, 304 >( 305 options: ServerOptions<Request, Response>, 306 requestListener?: http.RequestListener<Request, Response>, 307 ): Server<Request, Response>; 308 /** 309 * Makes a request to a secure web server. 310 * 311 * The following additional `options` from `tls.connect()` are also accepted:`ca`, `cert`, `ciphers`, `clientCertEngine`, `crl`, `dhparam`, `ecdhCurve`, `honorCipherOrder`, `key`, `passphrase`, 312 * `pfx`, `rejectUnauthorized`, `secureOptions`, `secureProtocol`, `servername`, `sessionIdContext`, `highWaterMark`. 313 * 314 * `options` can be an object, a string, or a `URL` object. If `options` is a 315 * string, it is automatically parsed with `new URL()`. If it is a `URL` object, it will be automatically converted to an ordinary `options` object. 316 * 317 * `https.request()` returns an instance of the `http.ClientRequest` class. The `ClientRequest` instance is a writable stream. If one needs to 318 * upload a file with a POST request, then write to the `ClientRequest` object. 319 * 320 * ```js 321 * import https from 'node:https'; 322 * 323 * const options = { 324 * hostname: 'encrypted.google.com', 325 * port: 443, 326 * path: '/', 327 * method: 'GET' 328 * }; 329 * 330 * const req = https.request(options, (res) => { 331 * console.log('statusCode:', res.statusCode); 332 * console.log('headers:', res.headers); 333 * 334 * res.on('data', (d) => { 335 * process.stdout.write(d); 336 * }); 337 * }); 338 * 339 * req.on('error', (e) => { 340 * console.error(e); 341 * }); 342 * req.end(); 343 * ``` 344 * 345 * Example using options from `tls.connect()`: 346 * 347 * ```js 348 * const options = { 349 * hostname: 'encrypted.google.com', 350 * port: 443, 351 * path: '/', 352 * method: 'GET', 353 * key: fs.readFileSync('test/fixtures/keys/agent2-key.pem'), 354 * cert: fs.readFileSync('test/fixtures/keys/agent2-cert.pem') 355 * }; 356 * options.agent = new https.Agent(options); 357 * 358 * const req = https.request(options, (res) => { 359 * // ... 360 * }); 361 * ``` 362 * 363 * Alternatively, opt out of connection pooling by not using an `Agent`. 364 * 365 * ```js 366 * const options = { 367 * hostname: 'encrypted.google.com', 368 * port: 443, 369 * path: '/', 370 * method: 'GET', 371 * key: fs.readFileSync('test/fixtures/keys/agent2-key.pem'), 372 * cert: fs.readFileSync('test/fixtures/keys/agent2-cert.pem'), 373 * agent: false 374 * }; 375 * 376 * const req = https.request(options, (res) => { 377 * // ... 378 * }); 379 * ``` 380 * 381 * Example using a `URL` as `options`: 382 * 383 * ```js 384 * const options = new URL('https://abc:xyz@example.com'); 385 * 386 * const req = https.request(options, (res) => { 387 * // ... 388 * }); 389 * ``` 390 * 391 * Example pinning on certificate fingerprint, or the public key (similar to`pin-sha256`): 392 * 393 * ```js 394 * import tls from 'node:tls'; 395 * import https from 'node:https'; 396 * import crypto from 'node:crypto'; 397 * 398 * function sha256(s) { 399 * return crypto.createHash('sha256').update(s).digest('base64'); 400 * } 401 * const options = { 402 * hostname: 'github.com', 403 * port: 443, 404 * path: '/', 405 * method: 'GET', 406 * checkServerIdentity: function(host, cert) { 407 * // Make sure the certificate is issued to the host we are connected to 408 * const err = tls.checkServerIdentity(host, cert); 409 * if (err) { 410 * return err; 411 * } 412 * 413 * // Pin the public key, similar to HPKP pin-sha25 pinning 414 * const pubkey256 = 'pL1+qb9HTMRZJmuC/bB/ZI9d302BYrrqiVuRyW+DGrU='; 415 * if (sha256(cert.pubkey) !== pubkey256) { 416 * const msg = 'Certificate verification error: ' + 417 * `The public key of '${cert.subject.CN}' ` + 418 * 'does not match our pinned fingerprint'; 419 * return new Error(msg); 420 * } 421 * 422 * // Pin the exact certificate, rather than the pub key 423 * const cert256 = '25:FE:39:32:D9:63:8C:8A:FC:A1:9A:29:87:' + 424 * 'D8:3E:4C:1D:98:DB:71:E4:1A:48:03:98:EA:22:6A:BD:8B:93:16'; 425 * if (cert.fingerprint256 !== cert256) { 426 * const msg = 'Certificate verification error: ' + 427 * `The certificate of '${cert.subject.CN}' ` + 428 * 'does not match our pinned fingerprint'; 429 * return new Error(msg); 430 * } 431 * 432 * // This loop is informational only. 433 * // Print the certificate and public key fingerprints of all certs in the 434 * // chain. Its common to pin the public key of the issuer on the public 435 * // internet, while pinning the public key of the service in sensitive 436 * // environments. 437 * do { 438 * console.log('Subject Common Name:', cert.subject.CN); 439 * console.log(' Certificate SHA256 fingerprint:', cert.fingerprint256); 440 * 441 * hash = crypto.createHash('sha256'); 442 * console.log(' Public key ping-sha256:', sha256(cert.pubkey)); 443 * 444 * lastprint256 = cert.fingerprint256; 445 * cert = cert.issuerCertificate; 446 * } while (cert.fingerprint256 !== lastprint256); 447 * 448 * }, 449 * }; 450 * 451 * options.agent = new https.Agent(options); 452 * const req = https.request(options, (res) => { 453 * console.log('All OK. Server matched our pinned cert or public key'); 454 * console.log('statusCode:', res.statusCode); 455 * // Print the HPKP values 456 * console.log('headers:', res.headers['public-key-pins']); 457 * 458 * res.on('data', (d) => {}); 459 * }); 460 * 461 * req.on('error', (e) => { 462 * console.error(e.message); 463 * }); 464 * req.end(); 465 * ``` 466 * 467 * Outputs for example: 468 * 469 * ```text 470 * Subject Common Name: github.com 471 * 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 472 * Public key ping-sha256: pL1+qb9HTMRZJmuC/bB/ZI9d302BYrrqiVuRyW+DGrU= 473 * Subject Common Name: DigiCert SHA2 Extended Validation Server CA 474 * 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 475 * Public key ping-sha256: RRM1dGqnDFsCJXBTHky16vi1obOlCgFFn/yOhI/y+ho= 476 * Subject Common Name: DigiCert High Assurance EV Root CA 477 * 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 478 * Public key ping-sha256: WoiWRyIOVNa9ihaBciRSC7XHjliYS9VwUGOIud4PB18= 479 * All OK. Server matched our pinned cert or public key 480 * statusCode: 200 481 * headers: max-age=0; pin-sha256="WoiWRyIOVNa9ihaBciRSC7XHjliYS9VwUGOIud4PB18="; pin-sha256="RRM1dGqnDFsCJXBTHky16vi1obOlCgFFn/yOhI/y+ho="; 482 * pin-sha256="k2v657xBsOVe1PQRwOsHsw3bsGT2VzIqz5K+59sNQws="; pin-sha256="K87oWBWM9UZfyddvDfoxL+8lpNyoUB2ptGtn0fv6G2Q="; pin-sha256="IQBnNBEiFuhj+8x6X8XLgh01V9Ic5/V3IRQLNFFc7v4="; 483 * pin-sha256="iie1VXtL7HzAMF+/PVPR9xzT80kQxdZeJ+zduCB3uj0="; pin-sha256="LvRiGEjRqfzurezaWuj8Wie2gyHMrW5Q06LspMnox7A="; includeSubDomains 484 * ``` 485 * @since v0.3.6 486 * @param options Accepts all `options` from `request`, with some differences in default values: 487 */ 488 function request( 489 options: RequestOptions | string | URL, 490 callback?: (res: http.IncomingMessage) => void, 491 ): http.ClientRequest; 492 function request( 493 url: string | URL, 494 options: RequestOptions, 495 callback?: (res: http.IncomingMessage) => void, 496 ): http.ClientRequest; 497 /** 498 * Like `http.get()` but for HTTPS. 499 * 500 * `options` can be an object, a string, or a `URL` object. If `options` is a 501 * string, it is automatically parsed with `new URL()`. If it is a `URL` object, it will be automatically converted to an ordinary `options` object. 502 * 503 * ```js 504 * import https from 'node:https'; 505 * 506 * https.get('https://encrypted.google.com/', (res) => { 507 * console.log('statusCode:', res.statusCode); 508 * console.log('headers:', res.headers); 509 * 510 * res.on('data', (d) => { 511 * process.stdout.write(d); 512 * }); 513 * 514 * }).on('error', (e) => { 515 * console.error(e); 516 * }); 517 * ``` 518 * @since v0.3.6 519 * @param options Accepts the same `options` as {@link request}, with the `method` always set to `GET`. 520 */ 521 function get( 522 options: RequestOptions | string | URL, 523 callback?: (res: http.IncomingMessage) => void, 524 ): http.ClientRequest; 525 function get( 526 url: string | URL, 527 options: RequestOptions, 528 callback?: (res: http.IncomingMessage) => void, 529 ): http.ClientRequest; 530 let globalAgent: Agent; 531 } 532 declare module "node:https" { 533 export * from "https"; 534 }