ja4

Parse JA4 TLS fingerprint strings into structured objects.

Install

# npm
npm install @hckhanh/ja4

# JSR
npx jsr add @hckhanh/ja4

Usage

import { parseJA4 } from "@hckhanh/ja4";

const result = parseJA4("t13d1516h2_8daaf6152771_02713d6af862");

console.log(result.sectionA.protocol); // "TCP"
console.log(result.sectionA.tlsVersion); // "1.3"
console.log(result.sectionA.sni); // "domain"
console.log(result.sectionA.cipherSuiteCount); // 15
console.log(result.sectionA.extensionCount); // 16
console.log(result.sectionA.alpn); // "h2"
console.log(result.cipherSuiteHash); // "8daaf6152771"
console.log(result.extensionHash); // "02713d6af862"

API

parseJA4(fingerprint: string): JA4Fingerprint

Parses a JA4 fingerprint string in the format {sectionA}_{sectionB}_{sectionC} and returns a structured object. Throws JA4ParseError if the input is invalid.

JA4Fingerprint

| Property | Type | Description | | ----------------- | ------------- | -------------------------------------------------------------- | | raw | string | The original fingerprint string | | sectionA | JA4SectionA | Parsed human-readable section | | cipherSuiteHash | string | 12-char truncated SHA256 hash of sorted cipher suites | | extensionHash | string | 12-char truncated SHA256 hash of sorted extensions + sig algos |

JA4SectionA

| Property | Type | Description | | ------------------ | -------- | ---------------------------------------------------------- | | raw | string | Raw section a string (e.g. "t13d1516h2") | | protocol | string | Transport protocol: "TCP", "QUIC", or "DTLS" | | tlsVersion | string | TLS version: "1.0", "1.1", "1.2", or "1.3" | | sni | string | "domain" (SNI present) or "ip" | | cipherSuiteCount | number | Number of cipher suites (excluding GREASE) | | extensionCount | number | Number of extensions (excluding GREASE) | | alpn | string | First ALPN value hint (first+last char), or "00" if none |

JA4ParseError

Extends Error. Thrown when the fingerprint string is malformed or contains invalid values.

import { JA4ParseError, parseJA4 } from "@hckhanh/ja4";

try {
  parseJA4("invalid");
} catch (error) {
  if (error instanceof JA4ParseError) {
    console.error(error.message);
  }
}

Concepts

JA4 Fingerprint

JA4 is a TLS client fingerprinting method that captures characteristics of a TLS Client Hello message into a compact string. It can be used to identify specific clients, detect malware, or flag unusual TLS behavior without decrypting traffic.

A JA4 fingerprint has three sections separated by underscores: {sectionA}_{sectionB}_{sectionC} (e.g. t13d1516h2_8daaf6152771_02713d6af862).

TLS (Transport Layer Security)

TLS is a cryptographic protocol that secures communication over a network. During connection setup, the client sends a Client Hello message advertising its supported ciphers, extensions, and protocol versions — this is what JA4 fingerprints.

TCP, QUIC, and DTLS

These are the transport protocols that can carry a TLS handshake. TCP is the traditional transport for TLS. QUIC is a UDP-based transport used by HTTP/3 that integrates TLS 1.3 directly. DTLS (Datagram TLS) provides TLS-like security over UDP for protocols that need datagram semantics. The first character of a JA4 fingerprint encodes which one was used (t, q, or d).

SNI (Server Name Indication)

SNI is a TLS extension that lets the client specify which hostname it is trying to reach. This allows a single IP address to host multiple TLS-secured domains. In JA4, d means a domain name was present in SNI, while i means SNI was not present (often seen when connecting by IP).

ALPN (Application-Layer Protocol Negotiation)

ALPN is a TLS extension that lets the client and server agree on an application protocol (e.g. h2 for HTTP/2, h3 for HTTP/3, or http/1.1 for HTTP/1.1) during the handshake. JA4 encodes the first and last character of the first ALPN value as a 2-character hint such as h2 or h1, or 00 if no ALPN extension was present.

Cipher Suites

A cipher suite is a set of cryptographic algorithms that the client supports for key exchange, encryption, and message authentication. The Client Hello lists all cipher suites the client is willing to use. JA4 section B contains a truncated SHA256 hash of the sorted cipher suite values.

TLS Extensions

TLS extensions allow clients and servers to negotiate additional capabilities beyond the base protocol (e.g. supported groups, key shares, signature algorithms). JA4 section C contains a truncated SHA256 hash of the sorted extension values combined with signature algorithms.

Signature Algorithms

Signature algorithms specify which cryptographic signing methods the client supports for verifying certificates and handshake messages. They are advertised via a TLS extension and are included in JA4's section C hash alongside other extensions.

GREASE (Generate Random Extensions And Sustain Extensibility)

GREASE values are dummy cipher suite and extension identifiers that clients inject into the Client Hello to prevent servers from becoming intolerant of new values. Because GREASE values are random and vary between connections, JA4 excludes them from cipher suite and extension counts to keep fingerprints stable.

AI Agents

If you use an AI agent, run npx @tanstack/intent@latest install

License

MIT