Package Exports
- node-tls-client
- node-tls-client/dist/index.js
This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (node-tls-client) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.
Readme
What is TLS Fingerprinting?
Some 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.Installation
npm install node-tls-client
# (or)
yarn add node-tls-client
# (or)
pnpm add node-tls-clientExample
const {
Session,
ClientIdentifier,
initTLS,
destroyTLS,
} = require("node-tls-client");
/**
* @description Demonstrates using the node-tls-client library to make HTTP requests with a specified timeout.
* Note: The timeout is set per session and cannot be changed during the session.
*
* @see {@link https://sahil1337.github.io/node-tls-client/interfaces/SessionOptions.html SessionOptions} for more details.
*/
(async () => {
await initTLS();
const session = new Session({
clientIdentifier: ClientIdentifier.chrome_103,
timeout: 3000,
});
try {
const response = await session.get("https://website.com/");
console.log(response.status, await response.text());
} catch (error) {
console.error("An error occurred:", error);
} finally {
await session.close();
await destroyTLS();
}
})();Advanced example
const { Session, initTLS, destroyTLS } = require("node-tls-client");
/**
* @description Demonstrates an advanced usage scenario with the node-tls-client library, showcasing custom TLS client configuration.
*
* This example illustrates the creation of a TLS session with tailored settings and the execution of a GET request.
*
* Custom TLS settings encompass a wide array of configurations, including:
* - JA3 string specification
* - Fine-tuning HTTP/2 settings
* - Defining supported signature algorithms
* - Specifying ALPN (Application-Layer Protocol Negotiation) protocols
* - Declaring supported TLS versions
* - Setting key share curves for cryptographic key exchange
* - Choosing a certificate compression algorithm
* - Configuring connection and header flow parameters
* - Defining the order of headers and priority frames
* - Providing default headers for HTTP requests
*
* @see {@link https://sahil1337.github.io/node-tls-client/interfaces/SessionOptions.html SessionOptions} for more details on session options.
*/
(async () => {
await initTLS();
const session = new Session({
ja3string:
"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",
h2Settings: {
HEADER_TABLE_SIZE: 65536,
MAX_CONCURRENT_STREAMS: 1000,
INITIAL_WINDOW_SIZE: 6291456,
MAX_HEADER_LIST_SIZE: 262144,
},
h2SettingsOrder: [
"HEADER_TABLE_SIZE",
"MAX_CONCURRENT_STREAMS",
"INITIAL_WINDOW_SIZE",
"MAX_HEADER_LIST_SIZE",
],
supportedSignatureAlgorithms: [
"ECDSAWithP256AndSHA256",
"PSSWithSHA256",
"PKCS1WithSHA256",
"ECDSAWithP384AndSHA384",
"PSSWithSHA384",
"PKCS1WithSHA384",
"PSSWithSHA512",
"PKCS1WithSHA512",
],
alpnProtocols: ["h2", "http/1.1"],
alpsProtocols: ["h2"],
supportedVersions: ["GREASE", "1.3", "1.2"],
keyShareCurves: ["GREASE", "X25519"],
certCompressionAlgo: "brotli",
pseudoHeaderOrder: [":method", ":authority", ":scheme", ":path"],
connectionFlow: 15663105,
headerOrder: ["accept", "user-agent", "accept-encoding", "accept-language"],
priorityFrames: [
{
streamID: 1,
priorityParam: {
streamDep: 1,
exclusive: true,
weight: 1,
},
},
],
headerPriority: {
streamDep: 1,
exclusive: true,
weight: 1,
},
headers: {
accept:
"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",
"user-agent":
"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",
"accept-encoding": "gzip, deflate, br",
"accept-language": "de-DE,de;q=0.9,en-US;q=0.8,en;q=0.7",
},
});
const response = await session.get("http://localhost:3000/");
console.log(response.status, await response.text());
await session.close();
await destroyTLS();
})();More examples
const { Session, ClientIdentifier, initTLS, destroyTLS } = require("node-tls-client");
(async () => {
await initTLS();
const session = new Session({
clientIdentifier: ClientIdentifier.chrome_120, //client identifier
timeout: 30 * 1000, //timeout in *milliseconds*, applies for each requests, checkout examples/timeout.js for using different timeouts.
insecureSkipVerify: false,
});
const response = await session.get("https://example.com", {
proxy: `http://user:pass@ip:port`, //proxy format: http://user:pass@ip:port or http://ip:port
cookies: { parameter: "value" }, //cookies
followRedirects: true, //follow redirected urls
headers: { authorization: "test" }, //request headers
});
console.log(response.status);
await session.close();
await destroyTLS();
})();
//more details: https://sahil1337.github.io/node-tls-client/hierarchy.html#BaseRequestOptionsSession
Session Options
| Property | Type | Description |
|---|---|---|
sessionId |
string | A unique identifier for the session. |
headers |
IncomingHttpHeaders | An object containing custom headers to send with the request. |
proxy |
string | A proxy server URL to use for the request. [format: 'http://user:pass@ip:port or http://ip:port'] |
isRotatingProxy |
boolean | Whether the proxy is of rotating type or not. |
clientIdentifier |
ClientIdentifier | A string identifier for the client, e.g., "chrome_120". |
ja3string |
string | A string representing JA3 fingerprinting configuration. |
h2Settings |
h2Settings[] | An object specifying HTTP/2 settings. |
h2SettingsOrder |
h2Settings[] | An array specifying the order of HTTP/2 settings. |
supportedSignatureAlgorithms |
supportedSignatureAlgorithms[] | An array of supported signature algorithms. |
supportedVersions |
supportedVersions[] | An array of supported TLS versions. |
keyShareCurves |
keyShareCurves[] | An array of key share curves. |
certCompressionAlgo |
certCompressionAlgo | A certificate compression algorithm, e.g., "brotli". |
pseudoHeaderOrder |
pseudoHeaderOrder[] | An array specifying the order of pseudo-headers. |
connectionFlow |
number | A number specifying the connection flow control window size. |
priorityFrames |
priorityFrame[] | An array of priority frames to send with the request. |
headerOrder |
string[] | An array specifying the order of headers. |
alpnProtocols |
string[] | An array of Application-Layer Protocol Negotiation (ALPN) protocols. |
alpsProtocols |
string[] | An array of Application Layer Protocol Settings (ALPS) protocols. |
headerPriority |
priorityParam | An object specifying header priority parameters. |
randomTlsExtensionOrder |
boolean | A boolean indicating whether to use a random order for TLS extensions. |
forceHttp1 |
boolean | A boolean indicating whether to force the use of HTTP/1.1. |
debug |
boolean | A boolean indicating whether to enable debug mode. |
insecureSkipVerify |
boolean | A boolean indicating whether to skip SSL certificate verification. |
Session methods
| Method | Description |
|---|---|
get(url: string, options: RequestOptions) |
Sends a GET request to the specified URL and returns the response. |
put(url: string, options: RequestOptions) |
Sends a PUT request to the specified URL with the provided options and returns the response. |
delete(url: string, options: RequestOptions) |
Sends a DELETE request to the specified URL with the provided options and returns the response. |
options(url: string, options: RequestOptions) |
Sends an OPTIONS request to the specified URL with the provided options and returns the response. |
head(url: string, options: RequestOptions) |
Sends a HEAD request to the specified URL with the provided options and returns the response. |
post(url: string, options: RequestOptions) |
Sends a POST request to the specified URL with the provided options and returns the response. |
patch(url: string, options: RequestOptions) |
Sends a PATCH request to the specified URL with the provided options and returns the response. |
close() |
Closes the session. |
cookies() |
Returns an promise that resolves with an object containing the session cookies. |
Request Options
| Parameter | Description |
|---|---|
body |
The body of the request, if applicable. This can be a string, a buffer, or an object. |
headers |
An object containing the request headers. |
followRedirects |
A boolean value indicating whether to follow redirects. |
additionalDecode |
A boolean value indicating whether to perform additional decoding of the response content. |
proxy |
The URL of the proxy server to be used for the request. [format: 'http://user:pass@ip:port or http://ip:port'] |
isRotatingProxy |
Whether the proxy is of rotating type or not. |
cookies |
An object containing cookies to be sent with the request. |
Response
| Properties | Description |
|---|---|
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".` |
headers |
This object contains the response headers returned by the server. |
status |
This integer represents the HTTP status code of the response. |
url |
This is the URL to which the request was made. |
cookies |
Returns an object containing the cookies for that URL. |
| Methods | Description |
|---|---|
text() |
Returns a promise that resolves with the response body as plain text. |
json() |
Returns a promise that resolves with the response body parsed as JSON. |
Acknowledgements
This library is based on bogdanfinn's tls client in golang. A big thanks to him.
