node-tls-client

library2.1.0jsnpmunverified

An advanced Node.js library for making HTTP requests with custom TLS fingerprinting to avoid server-side detection based on TLS handshake characteristics. Version 2.1.0 is the latest stable release. It wraps the tls-client Go binary, exposing a node-fetch-inspired API with Session-based management. Key differentiators: supports custom JA3 strings, HTTP/2 settings, signature algorithms, ALPN protocols, and header ordering. Requires initialization/destruction of the underlying binary. Drawback: per-session timeout cannot be changed. Ships TypeScript definitions.

security

npm install node-tls-client

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · NODE-TLS-CLIENT

node-tls-client

securityjavascriptv2.1.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Session

✓ import { Session } from 'node-tls-client'

✗ const Session = require('node-tls-client').Session

CommonJS require works but named import is preferred; ESM import is supported.

ClientIdentifier

✓ import { ClientIdentifier } from 'node-tls-client'

✗ import { ClientIdentifier } from 'node-tls-client'

Exported as a const object; use dot notation like ClientIdentifier.chrome_103.

initTLS

✓ import { initTLS } from 'node-tls-client'

✗ import initTLS from 'node-tls-client'

initTLS is a named export, not default.

Demonstrates creating a TLS session with Chrome 103 fingerprint and making a GET request, including initialization and cleanup.

import { Session, ClientIdentifier, initTLS, destroyTLS } from 'node-tls-client'; (async () => { await initTLS(); const session = new Session({ clientIdentifier: ClientIdentifier.chrome_103, timeout: 5000, }); try { const response = await session.get('https://httpbin.org/get'); console.log(response.status, await response.text()); } catch (error) { console.error('Request failed:', error); } finally { await session.close(); await destroyTLS(); } })();

Debug

Known issues

gotchaThe timeout option is set per-session and cannot be changed after the session is created.

fix

Create a new Session instance with the desired timeout if you need to change it.

affects: >=2.0.0

deprecatedClientIdentifier.chrome_103 and other browser identifiers may become outdated as browsers update their TLS fingerprints.

fix

Use custom JA3 strings via the ja3string option instead of relying on hardcoded identifiers.

affects: >=2.0.0

gotchainitTLS() and destroyTLS() must be called exactly once per process lifecycle. Multiple calls can cause undefined behavior.

fix

Call initTLS() once on application startup and destroyTLS() on shutdown. Use a flag to ensure single calls.

affects: >=2.0.0

gotchaThe library spawns an external Go binary (tls-client) that must be present in the system PATH. Installation via npm does not automatically add the binary.

fix

Install tls-client separately: npm install -g @ulixee/tls-client (or follow installation instructions on GitHub).

affects: >=2.0.0

gotchaSession.close() should be called after each session to release resources; failing to do so may cause memory leaks.

fix

Always wrap session usage in try/finally and call session.close().

affects: >=2.0.0

Errors

Common errors & fixes

Error: Cannot find module 'node-tls-client'

Package not installed or incorrect import path.

fix

Run 'npm install node-tls-client' and ensure import path is correct (use 'node-tls-client' not './node-tls-client').

TypeError: initTLS is not a function

initTLS was not imported correctly; common mistake is default import instead of named import.

fix

Use 'import { initTLS } from 'node-tls-client'' instead of 'import initTLS from ...'.

Error: TLS client binary not found

tls-client Go binary is not installed or not in PATH.

fix

Install tls-client globally: 'npm install -g @ulixee/tls-client' or download from https://github.com/ulixee/ulixee/releases and add to PATH.

Error: Timeout of 0ms exceeded

Session timeout set to 0 or very low value; or request took longer than timeout.

fix

Set a reasonable timeout (> 0) or increase timeout value. Ensure network is reachable.

Upgrade

Version history

2.1.0latest on npm

Audit

Dependencies

node-fetchrequirednode-tls-client mimics node-fetch API for response objects (status, text(), json()).

Agent activity

30 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/Sahil1337/node-tls-client ↗

packagenode-tls-client ↗

homepagehttps://github.com/Sahil1337/node-tls-client#readme ↗