What is TLS Fingerprinting?
\r\nSome people think it is enough to change the user-agent header of a request to let the server think that the client requesting a resource is a specific browser. Nowadays this is not enough, because the server might use a technique to detect the client browser which is called TLS Fingerprinting.
This library aims to defeat it. \r\n\r\n## Installation\r\n\r\n```sh\r\nnpm install node-tls-client\r\n# (or)\r\nyarn add node-tls-client\r\n# (or)\r\npnpm add node-tls-client\r\n```\r\n\r\n## Example\r\n\r\n```javascript\r\nconst {\r\n Session,\r\n ClientIdentifier,\r\n initTLS,\r\n destroyTLS,\r\n} = require(\"node-tls-client\");\r\n\r\n/**\r\n * @description Demonstrates using the node-tls-client library to make HTTP requests with a specified timeout.\r\n * Note: The timeout is set per session and cannot be changed during the session.\r\n *\r\n * @see {@link https://sahil1337.github.io/node-tls-client/interfaces/SessionOptions.html SessionOptions} for more details.\r\n */\r\n(async () => {\r\n await initTLS();\r\n\r\n const session = new Session({\r\n clientIdentifier: ClientIdentifier.chrome_103,\r\n timeout: 3000,\r\n });\r\n\r\n try {\r\n const response = await session.get(\"https://website.com/\");\r\n\r\n console.log(response.status, await response.text());\r\n } catch (error) {\r\n console.error(\"An error occurred:\", error);\r\n } finally {\r\n await session.close();\r\n await destroyTLS();\r\n }\r\n})();\r\n```\r\n\r\n## Advanced example\r\n\r\n```javascript\r\nconst { Session, initTLS, destroyTLS } = require(\"node-tls-client\");\r\n\r\n/**\r\n * @description Demonstrates an advanced usage scenario with the node-tls-client library, showcasing custom TLS client configuration.\r\n *\r\n * This example illustrates the creation of a TLS session with tailored settings and the execution of a GET request.\r\n *\r\n * Custom TLS settings encompass a wide array of configurations, including:\r\n * - JA3 string specification\r\n * - Fine-tuning HTTP/2 settings\r\n * - Defining supported signature algorithms\r\n * - Specifying ALPN (Application-Layer Protocol Negotiation) protocols\r\n * - Declaring supported TLS versions\r\n * - Setting key share curves for cryptographic key exchange\r\n * - Choosing a certificate compression algorithm\r\n * - Configuring connection and header flow parameters\r\n * - Defining the order of headers and priority frames\r\n * - Providing default headers for HTTP requests\r\n *\r\n * @see {@link https://sahil1337.github.io/node-tls-client/interfaces/SessionOptions.html SessionOptions} for more details on session options.\r\n */\r\n\r\n(async () => {\r\n await initTLS();\r\n\r\n const session = new Session({\r\n ja3string:\r\n \"771,2570-4865-4866-4867-49195-49199-49196-49200-52393-52392-49171-49172-156-157-47-53,2570-0-23-65281-10-11-35-16-5-13-18-51-45-43-27-17513-2570-21,2570-29-23-24,0\",\r\n h2Settings: {\r\n HEADER_TABLE_SIZE: 65536,\r\n MAX_CONCURRENT_STREAMS: 1000,\r\n INITIAL_WINDOW_SIZE: 6291456,\r\n MAX_HEADER_LIST_SIZE: 262144,\r\n },\r\n h2SettingsOrder: [\r\n \"HEADER_TABLE_SIZE\",\r\n \"MAX_CONCURRENT_STREAMS\",\r\n \"INITIAL_WINDOW_SIZE\",\r\n \"MAX_HEADER_LIST_SIZE\",\r\n ],\r\n supportedSignatureAlgorithms: [\r\n \"ECDSAWithP256AndSHA256\",\r\n \"PSSWithSHA256\",\r\n \"PKCS1WithSHA256\",\r\n \"ECDSAWithP384AndSHA384\",\r\n \"PSSWithSHA384\",\r\n \"PKCS1WithSHA384\",\r\n \"PSSWithSHA512\",\r\n \"PKCS1WithSHA512\",\r\n ],\r\n alpnProtocols: [\"h2\", \"http/1.1\"],\r\n alpsProtocols: [\"h2\"],\r\n supportedVersions: [\"GREASE\", \"1.3\", \"1.2\"],\r\n keyShareCurves: [\"GREASE\", \"X25519\"],\r\n certCompressionAlgo: \"brotli\",\r\n pseudoHeaderOrder: [\":method\", \":authority\", \":scheme\", \":path\"],\r\n connectionFlow: 15663105,\r\n headerOrder: [\"accept\", \"user-agent\", \"accept-encoding\", \"accept-language\"],\r\n priorityFrames: [\r\n {\r\n streamID: 1,\r\n priorityParam: {\r\n streamDep: 1,\r\n exclusive: true,\r\n weight: 1,\r\n },\r\n },\r\n ],\r\n headerPriority: {\r\n streamDep: 1,\r\n exclusive: true,\r\n weight: 1,\r\n },\r\n headers: {\r\n accept:\r\n \"application/json,text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.9\",\r\n \"user-agent\":\r\n \"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/105.0.0.0 Safari/537.36\",\r\n \"accept-encoding\": \"gzip, deflate, br\",\r\n \"accept-language\": \"de-DE,de;q=0.9,en-US;q=0.8,en;q=0.7\",\r\n },\r\n });\r\n\r\n const response = await session.get(\"http://localhost:3000/\");\r\n console.log(response.status, await response.text());\r\n await session.close();\r\n\r\n await destroyTLS();\r\n})();\r\n```\r\n\r\n## More examples\r\n```javascript\r\nconst { Session, ClientIdentifier, initTLS, destroyTLS } = require(\"node-tls-client\");\r\n\r\n(async () => {\r\n await initTLS();\r\n\r\n const session = new Session({\r\n clientIdentifier: ClientIdentifier.chrome_120, //client identifier\r\n timeout: 30 * 1000, //timeout in *milliseconds*, applies for each requests, checkout examples/timeout.js for using different timeouts.\r\n insecureSkipVerify: false,\r\n });\r\n \r\n const response = await session.get(\"https://example.com\", {\r\n proxy: `http://user:pass@ip:port`, //proxy format: http://user:pass@ip:port or http://ip:port\r\n cookies: { parameter: \"value\" }, //cookies\r\n followRedirects: true, //follow redirected urls\r\n headers: { authorization: \"test\" }, //request headers\r\n });\r\n\r\n console.log(response.status);\r\n\r\n await session.close();\r\n await destroyTLS();\r\n})();\r\n //more details: https://sahil1337.github.io/node-tls-client/hierarchy.html#BaseRequestOptions\r\n```\r\n\r\n## Session\r\n\r\n\r\n\r\n## Session Options\r\n\r\n| Property | Type | Description |\r\n| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |\r\n| `sessionId` | string | A unique identifier for the session. |\r\n| `headers` | IncomingHttpHeaders | An object containing custom headers to send with the request. |\r\n| `proxy` | string | A proxy server URL to use for the request. [format: 'http://user:pass@ip:port or http://ip:port']\r\n| `isRotatingProxy` | boolean | Whether the proxy is of rotating type or not. |\r\n| `clientIdentifier` | [ClientIdentifier](https://sahil1337.github.io/node-tls-client/enums/ClientIdentifier.html) | A string identifier for the client, e.g., `\"chrome_120\"`. |\r\n| `ja3string` | string | A string representing JA3 fingerprinting configuration. |\r\n| `h2Settings` | [h2Settings](https://sahil1337.github.io/node-tls-client/interfaces/H2Settings.html)[] | An object specifying HTTP/2 settings. |\r\n| `h2SettingsOrder` | [h2Settings](https://sahil1337.github.io/node-tls-client/interfaces/H2Settings.html)[] | An array specifying the order of HTTP/2 settings. |\r\n| `supportedSignatureAlgorithms` | [supportedSignatureAlgorithms](https://sahil1337.github.io/node-tls-client/types/SupportedSignatureAlgorithms.html)[] | An array of supported signature algorithms. |\r\n| `supportedVersions` | [supportedVersions](https://sahil1337.github.io/node-tls-client/types/SupportedVersions.html)[] | An array of supported TLS versions. |\r\n| `keyShareCurves` | [keyShareCurves](https://sahil1337.github.io/node-tls-client/types/KeyShareCurves.html)[] | An array of key share curves. |\r\n| `certCompressionAlgo` | [certCompressionAlgo](https://sahil1337.github.io/node-tls-client/types/CertCompressionAlgo.html) | A certificate compression algorithm, e.g., `\"brotli\"`. |\r\n| `pseudoHeaderOrder` | [pseudoHeaderOrder](https://sahil1337.github.io/node-tls-client/types/PseudoHeaderOrder.html)[] | An array specifying the order of pseudo-headers. |\r\n| `connectionFlow` | number | A number specifying the connection flow control window size. |\r\n| `priorityFrames` | [priorityFrame](https://sahil1337.github.io/node-tls-client/interfaces/PriorityFrames.html)[] | An array of priority frames to send with the request. |\r\n| `headerOrder` | string[] | An array specifying the order of headers. |\r\n| `alpnProtocols` | string[] | An array of Application-Layer Protocol Negotiation (ALPN) protocols. |\r\n| `alpsProtocols` | string[] | An array of Application Layer Protocol Settings (ALPS) protocols. |\r\n| `headerPriority` | [priorityParam](https://sahil1337.github.io/node-tls-client/interfaces/PriorityParam.html) | An object specifying header priority parameters. |\r\n| `randomTlsExtensionOrder` | boolean | A boolean indicating whether to use a random order for TLS extensions. |\r\n| `forceHttp1` | boolean | A boolean indicating whether to force the use of HTTP/1.1. |\r\n| `debug` | boolean | A boolean indicating whether to enable debug mode. |\r\n| `insecureSkipVerify` | boolean | A boolean indicating whether to skip SSL certificate verification. |\r\n\r\n
\r\n\r\n\r\n\r\n## Session methods\r\n\r\n| Method | Description |\r\n| ----------------------------------------------- | ------------------------------------------------------------------------------------------------- |\r\n| `get(url: string, options: RequestOptions)` | Sends a GET request to the specified URL and returns the response. |\r\n| `put(url: string, options: RequestOptions)` | Sends a PUT request to the specified URL with the provided options and returns the response. |\r\n| `delete(url: string, options: RequestOptions)` | Sends a DELETE request to the specified URL with the provided options and returns the response. |\r\n| `options(url: string, options: RequestOptions)` | Sends an OPTIONS request to the specified URL with the provided options and returns the response. |\r\n| `head(url: string, options: RequestOptions)` | Sends a HEAD request to the specified URL with the provided options and returns the response. |\r\n| `post(url: string, options: RequestOptions)` | Sends a POST request to the specified URL with the provided options and returns the response. |\r\n| `patch(url: string, options: RequestOptions)` | Sends a PATCH request to the specified URL with the provided options and returns the response. |\r\n| `close()` | Closes the session. |\r\n| `cookies()` | Returns an promise that resolves with an object containing the session cookies. |\r\n\r\n
\r\n\r\n## Request Options\r\n\r\n| Parameter | Description |\r\n| -------------------- | ----------------------------------------------------------------------------------------------- |\r\n| `body` | The body of the request, if applicable. This can be a string, a buffer, or an object. |\r\n| `headers` | An object containing the request headers. |\r\n| `followRedirects` | A boolean value indicating whether to follow redirects. |\r\n| `additionalDecode` | A boolean value indicating whether to perform additional decoding of the response content. |\r\n| `proxy` | The URL of the proxy server to be used for the request. [format: 'http://user:pass@ip:port or http://ip:port'] |\r\n| `isRotatingProxy` | Whether the proxy is of rotating type or not. |\r\n| `cookies` | An object containing cookies to be sent with the request. |\r\n\r\n
\r\n\r\n
\r\n\r\n## Response\r\n\r\n| Properties | Description |\r\n| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\r\n| `ok` | This boolean value indicates whether the request was successful or not. It returns \"true\" if the response status is within the range 200-299, indicating success. Otherwise, it returns \"false\".` |\r\n| `headers` | This object contains the response headers returned by the server. |\r\n| `status` | This integer represents the HTTP status code of the response. |\r\n| `url` | This is the URL to which the request was made. |\r\n| `cookies` | Returns an object containing the cookies for that URL. \r\n\r\n| Methods | Description |\r\n| ----------- | ------------------------------------------------------------------------------------ |\r\n| `text()` | Returns a promise that resolves with the response body as plain text. |\r\n| `json()` | Returns a promise that resolves with the response body parsed as JSON. |\r\n\r\n
\r\n\r\n\r\n\r\n## Acknowledgements\r\nThis library is based on [bogdanfinn's](https://github.com/bogdanfinn) tls client in golang. A big thanks to him.\r\n","readmeFilename":"readme.md"}
![\"NPM](\"https://img.shields.io/npm/v/node-tls-client?maxAge=3600\")
![\"NPM](\"https://img.shields.io/npm/dt/node-tls-client?maxAge=3600\")
![\"NPM](\"https://nodei.co/npm/node-tls-client.png?downloads=true&stars=true\")
\r\n