Add support for extension names in getExtensionData

Author: pimterry

README.md

@@ -58,7 +58,7 @@ GREASE values are preserved (they're what the client actually sent). The `calcul
 
 Extensions with registered parsers return structured data. Flag extensions (like `extended_master_secret` or `signed_certificate_timestamp`) return `{}`. Unrecognized, unparseable or GREASE extensions return `null`. If an extension parser encounters malformed data, it falls back to `null` rather than failing the entire parse.
 
-Parsed extensions include: `server_name`, `max_fragment_length`, `status_request`, `supported_groups`, `ec_point_formats`, `signature_algorithms`, `heartbeat`, `application_layer_protocol_negotiation`, `status_request_v2`, `signed_certificate_timestamp`, `padding`, `encrypt_then_mac`, `extended_master_secret`, `compress_certificate`, `record_size_limit`, `session_ticket`, `pre_shared_key`, `early_data`, `supported_versions`, `cookie`, `psk_key_exchange_modes`, `post_handshake_auth`, `signature_algorithms_cert`, `key_share`, `application_settings` (ALPS), `encrypted_client_hello` (ECH), and `renegotiation_info`.
+Parsed extensions include: `server_name` (SNI), `max_fragment_length`, `status_request`, `supported_groups`, `ec_point_formats`, `signature_algorithms`, `heartbeat`, `application_layer_protocol_negotiation` (ALPN), `status_request_v2`, `signed_certificate_timestamp`, `padding`, `encrypt_then_mac`, `extended_master_secret`, `compress_certificate`, `record_size_limit`, `session_ticket`, `pre_shared_key`, `early_data`, `supported_versions`, `cookie`, `psk_key_exchange_modes`, `post_handshake_auth`, `signature_algorithms_cert`, `key_share`, `application_settings` (ALPS), `encrypted_client_hello` (ECH), and `renegotiation_info`.
 
 ### TLS fingerprinting
 
@@ -69,9 +69,35 @@ To calculate TLS fingerprints, there are a few options exported from this module
 * `calculateJa3(clientHello)` - Takes a parsed `TlsClientHelloMessage` and returns the corresponding JA3 hash.
 * `calculateJa4(clientHello)` - Takes a parsed `TlsClientHelloMessage` and returns the corresponding JA4 hash.
 
+### Accessing extension data
+
+Use `getExtensionData(extensions, id)` to look up a specific extension's parsed data by numeric ID, name, or alias. Returns the data object, or `null` if the extension is not present.
+
+Names should be the officially registered name from https://www.iana.org/assignments/tls-extensiontype-values/tls-extensiontype-values.xhtml. Convenient aliases are provided for common cases, including `sni`, `alpn`, `alps` and `ech`. The API is typed so with TypeScript only valid names are allowed (although any raw numeric id can be used). PRs to add more aliases are welcome.
+
+```javascript
+const { readTlsClientHello, getExtensionData, EXTENSION_IDS } = require('read-tls-client-hello');
+
+const clientHello = await readTlsClientHello(socket);
+
+// Get the server name (SNI)
+const sniData = getExtensionData(clientHello.extensions, 'sni'); // or 'server_name', or 0x0
+const serverName = sniData?.serverName;
+
+// Get ALPN protocols
+const alpnData = getExtensionData(clientHello.extensions, 'alpn');
+const protocols = alpnData?.protocols;
+
+// Get supported TLS versions
+const svData = getExtensionData(clientHello.extensions, 'supported_versions');
+const versions = svData?.versions; // e.g. [0x0304, 0x0303]
+```
+
 ### Lookup tables
 
-All hello details (extensions, ciphers, etc) are exposed in `clientHello` with only numeric ids. To get human-readable names, lookup tables are provided:
+All hello details (extensions, ciphers, etc) are exposed with numeric IDs. Lookup tables map these to human-readable names. All tables are fully typed with `as const`, so known keys return literal values, which other keys' values may be undefined.
+
+Forward tables (ID → name) for display:
 
 * `TLS_VERSIONS` - e.g. `0x0303` → `'TLS 1.2'`
 * `CIPHER_SUITES` - e.g. `0x1301` → `'TLS_AES_128_GCM_SHA256'`
@@ -84,8 +110,12 @@ All hello details (extensions, ciphers, etc) are exposed in `clientHello` with o
 * `CERTIFICATE_COMPRESSION_ALGORITHMS` - e.g. `2` → `'brotli'`
 * `CERTIFICATE_STATUS_TYPES` - e.g. `1` → `'ocsp'`
 
+A reverse table (name → ID) is also available for extensions:
+
+* `EXTENSION_IDS` - e.g. `EXTENSION_IDS.key_share` → `51`, with aliases: `sni` (0), `alpn` (16), `alps` (17513), `ech` (65037)
+
 ```javascript
-const { CIPHER_SUITES, EXTENSIONS, isGREASE } = require('read-tls-client-hello');
+const { CIPHER_SUITES, isGREASE } = require('read-tls-client-hello');
 
 const cipherNames = clientHello.cipherSuites
     .filter(id => !isGREASE(id))

src/index.ts

@@ -4,6 +4,8 @@ import * as tls from 'tls';
 import * as net from 'net';
 
 import { extensionParsers } from './extension-parsers';
+import { EXTENSION_IDS } from './lookup-tables';
+import type { ExtensionName } from './lookup-tables';
 
 export { extensionParsers } from './extension-parsers';
 export * from './lookup-tables';
@@ -71,8 +73,11 @@ export type TlsClientHelloMessage = {
     extensions: TlsExtension[];
 };
 
-export function getExtensionData(extensions: TlsExtension[], id: number) {
-    return extensions.find(e => e.id === id)?.data ?? null;
+export function getExtensionData(extensions: TlsExtension[], id: number | ExtensionName) {
+    const numId = typeof id === 'string'
+        ? EXTENSION_IDS[id]
+        : id;
+    return extensions.find(e => e.id === numId)?.data ?? null;
 }
 
 /**

src/lookup-tables.ts

@@ -392,7 +392,8 @@ export const CIPHER_SUITES = lookupTable({
 });
 
 // https://www.iana.org/assignments/tls-extensiontype-values/tls-extensiontype-values.xhtml
-export const EXTENSIONS = lookupTable({
+// Internal const object — the single source of truth for both EXTENSIONS and EXTENSION_IDS.
+const _extensions = {
     0: 'server_name',
     1: 'max_fragment_length',
     2: 'client_certificate_url',
@@ -459,7 +460,31 @@ export const EXTENSIONS = lookupTable({
     65281: 'renegotiation_info',
     // Non-IANA but widely deployed
     17513: 'application_settings',
-});
+} as const satisfies Record<number, string>;
+
+export const EXTENSIONS: LookupTable<typeof _extensions> = _extensions as LookupTable<typeof _extensions>;
+
+// Reverse mapping: extension name (or alias) → numeric ID, derived from _extensions.
+type ExtKey = keyof typeof _extensions;
+type ExtVal = (typeof _extensions)[ExtKey];
+type ReverseExtensions = { readonly [V in ExtVal]: { [K in ExtKey]: (typeof _extensions)[K] extends V ? K : never }[ExtKey] };
+
+const _extensionAliases = {
+    sni: 0,
+    alpn: 16,
+    alps: 17513,
+    ech: 65037,
+} as const satisfies Record<string, number>;
+
+export const EXTENSION_IDS: ReverseExtensions & typeof _extensionAliases & Record<string, number | undefined> =
+    Object.assign(
+        Object.fromEntries(
+            Object.entries(_extensions).map(([id, name]) => [name, Number(id)])
+        ),
+        _extensionAliases
+    ) as any;
+
+export type ExtensionName = keyof (ReverseExtensions & typeof _extensionAliases);
 
 // https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-8
 export const SUPPORTED_GROUPS = lookupTable({

test/test.spec.ts

@@ -799,51 +799,30 @@ describe("Lookup tables", () => {
 
 describe("getExtensionData", () => {
 
-    it("retrieves SNI from a Chrome ClientHello", async () => {
+    it("retrieves extensions by alias", async () => {
         const incomingData = fs.createReadStream(path.join(__dirname, 'fixtures', 'chrome-tls-connect.bin'));
         const clientHello = await readTlsClientHello(incomingData);
 
-        const sni = getExtensionData(clientHello.extensions, 0x0000) as { serverName: string };
+        const sni = getExtensionData(clientHello.extensions, 'sni') as { serverName: string };
         expect(sni.serverName).to.equal('localhost');
+
+        const alpn = getExtensionData(clientHello.extensions, 'alpn') as { protocols: string[] };
+        expect(alpn.protocols).to.deep.equal(['h2', 'http/1.1']);
     });
 
-    it("retrieves ALPN from a Chrome ClientHello", async () => {
+    it("retrieves extensions by IDs", async () => {
         const incomingData = fs.createReadStream(path.join(__dirname, 'fixtures', 'chrome-tls-connect.bin'));
         const clientHello = await readTlsClientHello(incomingData);
 
-        const alpn = getExtensionData(clientHello.extensions, 0x0010) as { protocols: string[] };
-        expect(alpn.protocols).to.deep.equal(['h2', 'http/1.1']);
+        const sni = getExtensionData(clientHello.extensions, 0x0) as { serverName: string };
+        expect(sni.serverName).to.equal('localhost');
     });
 
     it("returns null for absent extensions", async () => {
         const incomingData = fs.createReadStream(path.join(__dirname, 'fixtures', 'chrome-tls-connect.bin'));
         const clientHello = await readTlsClientHello(incomingData);
-
-        // heartbeat is not present in the Chrome fixture
-        expect(getExtensionData(clientHello.extensions, 0x000F)).to.equal(null);
+        expect(getExtensionData(clientHello.extensions, 'heartbeat')).to.equal(null);
+        expect(getExtensionData(clientHello.extensions, 98765)).to.equal(null);
     });
 
-    let server: net.Server & { destroy?: () => Promise<void> };
-    afterEach(() => server?.destroy?.().catch(() => {}));
-
-    it("returns null for SNI/ALPN when not present", async () => {
-        const netServer = makeDestroyable(new net.Server());
-        server = netServer;
-
-        netServer.listen();
-        await new Promise((resolve) => netServer.on('listening', resolve));
-
-        let incomingSocketPromise = getDeferred<net.Socket>();
-        netServer.on('connection', (socket) => incomingSocketPromise.resolve(socket));
-
-        const port = (netServer.address() as net.AddressInfo).port;
-        tls.connect({ host: 'localhost', port }).on('error', () => {});
-
-        const incomingSocket = await incomingSocketPromise;
-        const clientHello = await readTlsClientHello(incomingSocket);
-
-        // Pure TLS connection without SNI or ALPN
-        expect(getExtensionData(clientHello.extensions, 0x0000)).to.equal(null);
-        expect(getExtensionData(clientHello.extensions, 0x0010)).to.equal(null);
-    });
 });