@joclaim/tls 0.1.0

package/lib/utils/packets.d.ts

@@ -0,0 +1,51 @@
+import type { Logger, TLSPacketWithType, TLSProtocolVersion } from '../types/index.ts';
+import { PACKET_TYPE } from './constants.ts';
+type PacketType = keyof typeof PACKET_TYPE;
+export type PacketHeaderOptions = {
+    type: PacketType;
+    /**
+     * TLS version to use in the header packet
+     * */
+    version?: TLSProtocolVersion;
+};
+export type PacketOptions = PacketHeaderOptions & {
+    data: Uint8Array;
+};
+export declare function packPacketHeader(dataLength: number, { type, version }: PacketHeaderOptions): Uint8Array<ArrayBufferLike>;
+export declare function packPacket(opts: PacketOptions): Uint8Array<ArrayBufferLike>;
+/**
+ * Packs data prefixed with the length of the data;
+ * Length encoded UInt24 big endian
+ */
+export declare function packWith3ByteLength(data: Uint8Array): Uint8Array<ArrayBufferLike>;
+export declare function readWithLength(data: Uint8Array, lengthBytes?: number): Uint8Array<ArrayBuffer> | undefined;
+/**
+ * Read a prefix of the data, that is prefixed with the length of
+ * said data. Throws an error if the data is not long enough
+ *
+ * @param data total data to read from
+ * @param lengthBytes number of bytes to read the length from.
+ * Default is 2 bytes
+ */
+export declare function expectReadWithLength(data: Uint8Array, lengthBytes?: number): Uint8Array<ArrayBuffer>;
+/**
+ * Packs data prefixed with the length of the data;
+ * Length encoded UInt16 big endian
+ */
+export declare function packWithLength(data: Uint8Array): Uint8Array<ArrayBuffer>;
+/**
+ * Processes an incoming stream of TLS packets
+ */
+export declare function makeMessageProcessor(logger: Logger): {
+    getPendingBuffer(): Uint8Array<ArrayBufferLike>;
+    /**
+     * @param packet TLS packet;
+     * can be multiple packets concatenated
+     * or incomplete packet
+     * or a single packet
+     * @param onChunk handle a complete packet
+     */
+    onData(packet: Uint8Array): Generator<TLSPacketWithType, void, unknown>;
+    reset(): void;
+};
+export {};

package/lib/utils/packets.js

@@ -0,0 +1,148 @@
+import { PACKET_TYPE, TLS_PROTOCOL_VERSION_MAP } from "./constants.js";
+import { concatenateUint8Arrays, uint8ArrayToDataView } from "./generics.js";
+export function packPacketHeader(dataLength, { type, version = 'TLS1_2' }) {
+    const lengthBuffer = new Uint8Array(2);
+    const dataView = uint8ArrayToDataView(lengthBuffer);
+    dataView.setUint16(0, dataLength);
+    return concatenateUint8Arrays([
+        new Uint8Array([PACKET_TYPE[type]]),
+        TLS_PROTOCOL_VERSION_MAP[version],
+        lengthBuffer
+    ]);
+}
+export function packPacket(opts) {
+    return concatenateUint8Arrays([
+        packPacketHeader(opts.data.length, opts),
+        opts.data
+    ]);
+}
+/**
+ * Packs data prefixed with the length of the data;
+ * Length encoded UInt24 big endian
+ */
+export function packWith3ByteLength(data) {
+    return concatenateUint8Arrays([
+        new Uint8Array([0x00]),
+        packWithLength(data)
+    ]);
+}
+export function readWithLength(data, lengthBytes = 2) {
+    const dataView = uint8ArrayToDataView(data);
+    const length = lengthBytes === 1
+        ? dataView.getUint8(0)
+        : dataView.getUint16(lengthBytes === 3 ? 1 : 0);
+    if (data.length < lengthBytes + length) {
+        return undefined;
+    }
+    return data.slice(lengthBytes, lengthBytes + length);
+}
+/**
+ * Read a prefix of the data, that is prefixed with the length of
+ * said data. Throws an error if the data is not long enough
+ *
+ * @param data total data to read from
+ * @param lengthBytes number of bytes to read the length from.
+ * Default is 2 bytes
+ */
+export function expectReadWithLength(data, lengthBytes = 2) {
+    const result = readWithLength(data, lengthBytes);
+    if (!result) {
+        throw new Error(`Expected packet to have at least ${data.length + lengthBytes} bytes, got ${data.length}`);
+    }
+    return result;
+}
+/**
+ * Packs data prefixed with the length of the data;
+ * Length encoded UInt16 big endian
+ */
+export function packWithLength(data) {
+    const buffer = new Uint8Array(2 + data.length);
+    const dataView = uint8ArrayToDataView(buffer);
+    dataView.setUint16(0, data.length);
+    buffer.set(data, 2);
+    return buffer;
+}
+// const SUPPORTED_PROTO_VERSIONS = [
+// 	LEGACY_PROTOCOL_VERSION,
+// 	CURRENT_PROTOCOL_VERSION,
+// ]
+/**
+ * Processes an incoming stream of TLS packets
+ */
+export function makeMessageProcessor(logger) {
+    let currentMessageType = undefined;
+    let currentMessageHeader = undefined;
+    let buffer = new Uint8Array(0);
+    let bytesLeft = 0;
+    return {
+        getPendingBuffer() {
+            return buffer;
+        },
+        /**
+         * @param packet TLS packet;
+         * can be multiple packets concatenated
+         * or incomplete packet
+         * or a single packet
+         * @param onChunk handle a complete packet
+         */
+        *onData(packet) {
+            buffer = concatenateUint8Arrays([buffer, packet]);
+            while (buffer.length) {
+                // if we already aren't processing a packet
+                // this is the first byte
+                if (!currentMessageType) {
+                    if (buffer.length < 5) {
+                        // we don't have enough bytes to process the header
+                        // wait for more bytes
+                        break;
+                    }
+                    // bytes[0] tells us which packet type we're processing
+                    // bytes[1:2] tell us the protocol version
+                    // bytes[3:4] tell us the length of the packet
+                    const packTypeNum = buffer[0];
+                    currentMessageType = packTypeNum;
+                    // get the number of bytes we need to process
+                    // to complete the packet
+                    const buffDataView = uint8ArrayToDataView(buffer);
+                    bytesLeft = buffDataView.getUint16(3);
+                    currentMessageHeader = buffer.slice(0, 5);
+                    // const protoVersion = currentMessageHeader.slice(1, 3)
+                    // const isSupportedVersion = SUPPORTED_PROTO_VERSIONS
+                    // 	.some((v) => areUint8ArraysEqual(v, protoVersion))
+                    // if(!isSupportedVersion) {
+                    // 	throw new Error(`Unsupported protocol version (${protoVersion})`)
+                    // }
+                    // remove the packet header
+                    buffer = buffer.slice(5);
+                    logger.trace({ bytesLeft, recvBuffer: buffer.length, type: currentMessageType }, 'starting processing packet');
+                }
+                if (buffer.length < bytesLeft) {
+                    // we don't have enough bytes to process the packet
+                    // wait for more bytes
+                    break;
+                }
+                const body = buffer.slice(0, bytesLeft);
+                logger.trace({ type: currentMessageType }, 'got complete packet');
+                const pktWithType = {
+                    type: currentMessageType,
+                    packet: {
+                        header: currentMessageHeader,
+                        content: body
+                    }
+                };
+                currentMessageType = undefined;
+                // if the current chunk we have still has bytes left
+                // then that means we have another packet in the chunk
+                // this will be processed in the next iteration of the loop
+                buffer = buffer.slice(body.length);
+                yield pktWithType;
+            }
+        },
+        reset() {
+            currentMessageType = undefined;
+            currentMessageHeader = undefined;
+            buffer = new Uint8Array(0);
+            bytesLeft = 0;
+        }
+    };
+}

package/lib/utils/parse-alert.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Parse a TLS alert message
+ */
+export declare function parseTlsAlert(buffer: Uint8Array): {
+    level: "WARNING" | "FATAL";
+    description: "CLOSE_NOTIFY" | "UNEXPECTED_MESSAGE" | "BAD_RECORD_MAC" | "RECORD_OVERFLOW" | "HANDSHAKE_FAILURE" | "BAD_CERTIFICATE" | "UNSUPPORTED_CERTIFICATE" | "CERTIFICATE_REVOKED" | "CERTIFICATE_EXPIRED" | "CERTIFICATE_UNKNOWN" | "ILLEGAL_PARAMETER" | "UNKNOWN_CA" | "ACCESS_DENIED" | "DECODE_ERROR" | "DECRYPT_ERROR" | "PROTOCOL_VERSION" | "INSUFFICIENT_SECURITY" | "INTERNAL_ERROR" | "INAPPROPRIATE_FALLBACK" | "USER_CANCELED" | "MISSING_EXTENSION" | "UNSUPPORTED_EXTENSION" | "UNRECOGNIZED_NAME" | "BAD_CERTIFICATE_STATUS_RESPONSE" | "UNKNOWN_PSK_IDENTITY" | "CERTIFICATE_REQUIRED" | "NO_APPLICATION_PROTOCOL" | "DECRYPTION_FAILED_RESERVED" | "DECOMPRESSION_FAILURE" | "NO_CERTIFICATE_RESERVED" | "EXPORT_RESTRICTION_RESERVED" | "NO_RENEGOTIATION";
+};

package/lib/utils/parse-alert.js

@@ -0,0 +1,28 @@
+import { ALERT_DESCRIPTION, ALERT_LEVEL } from "./constants.js";
+import { uint8ArrayToDataView } from "./generics.js";
+const ALERT_LEVEL_ENTRIES = Object
+    .entries(ALERT_LEVEL);
+const ALERT_DESCRIPTION_ENTRIES = Object
+    .entries(ALERT_DESCRIPTION);
+/**
+ * Parse a TLS alert message
+ */
+export function parseTlsAlert(buffer) {
+    const view = uint8ArrayToDataView(buffer);
+    const level = view.getUint8(0);
+    const description = view.getUint8(1);
+    const levelStr = ALERT_LEVEL_ENTRIES
+        .find(([, value]) => value === level)?.[0];
+    if (!levelStr) {
+        throw new Error(`Unknown alert level ${level}`);
+    }
+    const descriptionStr = ALERT_DESCRIPTION_ENTRIES
+        .find(([, value]) => value === description)?.[0];
+    if (!descriptionStr) {
+        throw new Error(`Unknown alert description ${description}`);
+    }
+    return {
+        level: levelStr,
+        description: descriptionStr
+    };
+}

package/lib/utils/parse-certificate.d.ts

@@ -0,0 +1,29 @@
+import './additional-root-cas.js';
+import type { CertificatePublicKey, CipherSuite, Key, Logger, TLSProcessContext, X509Certificate } from '../types/index.ts';
+import { SUPPORTED_NAMED_CURVE_MAP, SUPPORTED_SIGNATURE_ALGS_MAP } from './constants.ts';
+import { defaultFetchCertificateBytes } from './x509.ts';
+type VerifySignatureOptions = {
+    signature: Uint8Array;
+    algorithm: keyof typeof SUPPORTED_SIGNATURE_ALGS_MAP;
+    publicKey: CertificatePublicKey;
+    signatureData: Uint8Array;
+};
+export declare function parseCertificates(data: Uint8Array, { version }: TLSProcessContext): {
+    certificates: X509Certificate[];
+    ctx: number;
+};
+export declare function parseServerCertificateVerify(data: Uint8Array): {
+    algorithm: "ECDSA_SECP256R1_SHA256" | "ECDSA_SECP384R1_SHA256" | "RSA_PSS_RSAE_SHA256" | "RSA_PKCS1_SHA256" | "RSA_PKCS1_SHA384" | "RSA_PKCS1_SHA512";
+    signature: Uint8Array<ArrayBuffer>;
+};
+export declare function verifyCertificateSignature({ signature, algorithm, publicKey, signatureData, }: VerifySignatureOptions): Promise<void>;
+export declare function getSignatureDataTls13(hellos: Uint8Array[] | Uint8Array, cipherSuite: CipherSuite): Promise<Uint8Array<ArrayBufferLike>>;
+type Tls12SignatureDataOpts = {
+    clientRandom: Uint8Array;
+    serverRandom: Uint8Array;
+    curveType: keyof typeof SUPPORTED_NAMED_CURVE_MAP;
+    publicKey: Key;
+};
+export declare function getSignatureDataTls12({ clientRandom, serverRandom, curveType, publicKey, }: Tls12SignatureDataOpts): Promise<Uint8Array<ArrayBufferLike>>;
+export declare function verifyCertificateChain(chain: X509Certificate[], host: string, logger: Logger, fetchCertificateBytes?: typeof defaultFetchCertificateBytes, additionalRootCAs?: X509Certificate[]): Promise<void>;
+export {};

package/lib/utils/parse-certificate.js

@@ -0,0 +1,188 @@
+import './additional-root-cas.js';
+import { crypto } from "../crypto/index.js";
+import { SUPPORTED_NAMED_CURVE_MAP, SUPPORTED_SIGNATURE_ALGS, SUPPORTED_SIGNATURE_ALGS_MAP } from "./constants.js";
+import { getHash } from "./decryption-utils.js";
+import { areUint8ArraysEqual, asciiToUint8Array, concatenateUint8Arrays } from "./generics.js";
+import { MOZILLA_ROOT_CA_LIST } from "./mozilla-root-cas.js";
+import { expectReadWithLength, packWithLength } from "./packets.js";
+import { defaultFetchCertificateBytes, loadX509FromDer, loadX509FromPem } from "./x509.js";
+const CERT_VERIFY_TXT = asciiToUint8Array('TLS 1.3, server CertificateVerify');
+let ROOT_CAS;
+export function parseCertificates(data, { version }) {
+    // context, kina irrelevant
+    const ctx = version === 'TLS1_3' ? read(1)[0] : 0;
+    // the data itself
+    data = readWLength(3);
+    const certificates = [];
+    while (data.length) {
+        // the certificate data
+        const cert = readWLength(3);
+        const certObj = loadX509FromDer(cert);
+        certificates.push(certObj);
+        if (version === 'TLS1_3') {
+            // extensions
+            readWLength(2);
+        }
+    }
+    return { certificates, ctx };
+    function read(bytes) {
+        const result = data.slice(0, bytes);
+        data = data.slice(bytes);
+        return result;
+    }
+    function readWLength(bytesLength = 2) {
+        const content = expectReadWithLength(data, bytesLength);
+        data = data.slice(content.length + bytesLength);
+        return content;
+    }
+}
+export function parseServerCertificateVerify(data) {
+    // data = readWLength(2)
+    const algorithmBytes = read(2);
+    const algorithm = SUPPORTED_SIGNATURE_ALGS.find(alg => (areUint8ArraysEqual(SUPPORTED_SIGNATURE_ALGS_MAP[alg]
+        .identifier, algorithmBytes)));
+    if (!algorithm) {
+        throw new Error(`Unsupported signature algorithm '${algorithmBytes}'`);
+    }
+    const signature = readWLength(2);
+    return { algorithm, signature };
+    function read(bytes) {
+        const result = data.slice(0, bytes);
+        data = data.slice(bytes);
+        return result;
+    }
+    function readWLength(bytesLength = 2) {
+        const content = expectReadWithLength(data, bytesLength);
+        data = data.slice(content.length + bytesLength);
+        return content;
+    }
+}
+export async function verifyCertificateSignature({ signature, algorithm, publicKey, signatureData, }) {
+    const { algorithm: cryptoAlg } = SUPPORTED_SIGNATURE_ALGS_MAP[algorithm];
+    const pubKey = await crypto.importKey(cryptoAlg, publicKey.buffer, 'public');
+    const verified = await crypto.verify(cryptoAlg, {
+        data: signatureData,
+        signature,
+        publicKey: pubKey
+    });
+    if (!verified) {
+        throw new Error(`${algorithm} signature verification failed`);
+    }
+}
+export async function getSignatureDataTls13(hellos, cipherSuite) {
+    const handshakeHash = await getHash(hellos, cipherSuite);
+    return concatenateUint8Arrays([
+        new Uint8Array(64).fill(0x20),
+        CERT_VERIFY_TXT,
+        new Uint8Array([0]),
+        handshakeHash
+    ]);
+}
+export async function getSignatureDataTls12({ clientRandom, serverRandom, curveType, publicKey, }) {
+    const publicKeyBytes = await crypto.exportKey(publicKey);
+    return concatenateUint8Arrays([
+        clientRandom,
+        serverRandom,
+        concatenateUint8Arrays([
+            new Uint8Array([3]),
+            SUPPORTED_NAMED_CURVE_MAP[curveType].identifier,
+        ]),
+        packWithLength(publicKeyBytes)
+            // pub key is packed with 1 byte length
+            .slice(1)
+    ]);
+}
+export async function verifyCertificateChain(chain, host, logger, fetchCertificateBytes = defaultFetchCertificateBytes, additionalRootCAs) {
+    const rootCAs = [
+        ...loadRootCAs(),
+        ...(additionalRootCAs || [])
+    ];
+    const leaf = chain[0];
+    const commonNames = [
+        ...leaf.getSubjectField('CN'),
+        ...leaf.getAlternativeDNSNames()
+    ];
+    if (!commonNames.some(cn => matchHostname(host, cn))) {
+        throw new Error(`Certificate is not for host ${host}`);
+    }
+    chain = [...chain]; // clone to allow appending fetched certs
+    for (let i = 0; i < chain.length; i++) {
+        const cert = chain[i];
+        const cn = cert.getSubjectField('CN');
+        if (!cert.isWithinValidity()) {
+            throw new Error(`Certificate ${cn} (i: ${i}) is outside validity`);
+        }
+        // look in our chain for issuer
+        let issuer = findIssuer(chain.slice(i + 1), cert);
+        // if not found, check in our root CAs
+        if (!issuer) {
+            issuer = findIssuer(rootCAs, cert);
+        }
+        // if not found, we'll try fetching it via AIA extension
+        if (!issuer) {
+            const aiaExt = cert.getAIAExtension();
+            if (!aiaExt) {
+                throw new Error(`Missing issuer for certificate ${cn} (i: ${i})`);
+            }
+            if (TLS_INTERMEDIATE_CA_CACHE?.[aiaExt]) {
+                issuer = TLS_INTERMEDIATE_CA_CACHE[aiaExt];
+            }
+            else {
+                logger.debug({ aiaExt, cn }, 'fetching issuer certificate via AIA extension');
+                const bytes = await fetchCertificateBytes(aiaExt);
+                issuer = await loadX509FromPem(bytes);
+                // we'll need to verify this cert below too
+                chain.push(issuer);
+                TLS_INTERMEDIATE_CA_CACHE[aiaExt] = issuer;
+            }
+        }
+        if (!issuer.isWithinValidity()) {
+            throw new Error(`Issuer Cert ${cn} is not within validity period`);
+        }
+        if (!(await issuer.verifyIssued(cert))) {
+            const icn = issuer.getSubjectField('CN');
+            throw new Error(`Verification of ${cn} failed by issuer ${icn} (i: ${i})`);
+        }
+    }
+}
+function findIssuer(chain, cert) {
+    for (const element of chain) {
+        if (element.isIssuer(cert)) {
+            return element;
+        }
+    }
+}
+/**
+ * Checks if a hostname matches a common name
+ * @param host the hostname, eg. "google.com"
+ * @param commonName the common name from the certificate,
+ * 	eg. "*.google.com", "google.com"
+ */
+function matchHostname(host, commonName) {
+    // write a regex to match the common name
+    // and check if it matches the hostname
+    const hostComps = host.split('.');
+    const cnComps = commonName.split('.');
+    if (cnComps.length !== hostComps.length) {
+        // can ignore the first component if it's a wildcard
+        if (cnComps[0] === '*'
+            && cnComps.length === hostComps.length + 1) {
+            cnComps.shift();
+        }
+        else {
+            return false;
+        }
+    }
+    return hostComps.every((comp, i) => (comp === cnComps[i]
+        || cnComps[i] === '*'));
+}
+function loadRootCAs() {
+    if (ROOT_CAS) {
+        return ROOT_CAS;
+    }
+    ROOT_CAS = MOZILLA_ROOT_CA_LIST.map(loadX509FromPem);
+    if (typeof TLS_ADDITIONAL_ROOT_CA_LIST !== 'undefined') {
+        ROOT_CAS.push(...TLS_ADDITIONAL_ROOT_CA_LIST.map(loadX509FromPem));
+    }
+    return ROOT_CAS;
+}

package/lib/utils/parse-client-hello.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Parse a full client hello message
+ */
+export declare function parseClientHello(data: Uint8Array): {
+    version: "TLS1_3" | "TLS1_2";
+    serverRandom: Uint8Array<ArrayBuffer>;
+    sessionId: Uint8Array<ArrayBuffer>;
+    cipherSuitesBytes: Uint8Array<ArrayBuffer>;
+    compressionMethodByte: number;
+    extensions: Partial<import("../index.ts").SupportedExtensionClientData>;
+};

package/lib/utils/parse-client-hello.js

@@ -0,0 +1,39 @@
+import { SUPPORTED_RECORD_TYPE_MAP } from "./constants.js";
+import { getTlsVersionFromBytes } from "./generics.js";
+import { expectReadWithLength } from "./packets.js";
+import { parseClientExtensions } from "./parse-extensions.js";
+/**
+ * Parse a full client hello message
+ */
+export function parseClientHello(data) {
+    const packetType = read(1)[0];
+    if (packetType !== SUPPORTED_RECORD_TYPE_MAP.CLIENT_HELLO) {
+        throw new Error(`Invalid record type for client hello (${packetType})`);
+    }
+    data = readWLength(3);
+    const versionBytes = read(2);
+    const version = getTlsVersionFromBytes(versionBytes);
+    const serverRandom = read(32);
+    const sessionId = readWLength(1);
+    const cipherSuitesBytes = readWLength(2);
+    const compressionMethodByte = readWLength(1)[0];
+    const extensions = parseClientExtensions(data);
+    return {
+        version,
+        serverRandom,
+        sessionId,
+        cipherSuitesBytes,
+        compressionMethodByte,
+        extensions,
+    };
+    function read(bytes) {
+        const result = data.slice(0, bytes);
+        data = data.slice(bytes);
+        return result;
+    }
+    function readWLength(bytesLength = 2) {
+        const content = expectReadWithLength(data, bytesLength);
+        data = data.slice(content.length + bytesLength);
+        return content;
+    }
+}

package/lib/utils/parse-extensions.d.ts

@@ -0,0 +1,11 @@
+import type { SupportedExtensionClientData, SupportedExtensionServerData } from '../types/index.ts';
+/**
+ * Parse a length-encoded list of extensions
+ * sent by the server
+ */
+export declare function parseServerExtensions(data: Uint8Array): Partial<SupportedExtensionServerData>;
+/**
+ * Parse a length-encoded list of extensions
+ * sent by the client
+ */
+export declare function parseClientExtensions(data: Uint8Array): Partial<SupportedExtensionClientData>;

package/lib/utils/parse-extensions.js

@@ -0,0 +1,74 @@
+import { SUPPORTED_EXTENSION_MAP, SUPPORTED_EXTENSIONS, SUPPORTED_NAMED_CURVE_MAP, SUPPORTED_NAMED_CURVES } from "./constants.js";
+import { areUint8ArraysEqual, getTlsVersionFromBytes, uint8ArrayToBinaryStr } from "./generics.js";
+import { expectReadWithLength } from "./packets.js";
+/**
+ * Parse a length-encoded list of extensions
+ * sent by the server
+ */
+export function parseServerExtensions(data) {
+    return parseExtensions(data, {
+        'ALPN': (extData) => {
+            const data = expectReadWithLength(extData);
+            const alpnBytes = expectReadWithLength(data, 1);
+            return uint8ArrayToBinaryStr(alpnBytes);
+        },
+        'SUPPORTED_VERSIONS': getTlsVersionFromBytes,
+        'PRE_SHARED_KEY': () => ({ supported: true }),
+        'KEY_SHARE': (extData) => {
+            const typeBytes = extData.slice(0, 2);
+            const type = SUPPORTED_NAMED_CURVES
+                .find(k => areUint8ArraysEqual(SUPPORTED_NAMED_CURVE_MAP[k].identifier, typeBytes));
+            if (!type) {
+                throw new Error(`Unsupported key type '${typeBytes}'`);
+            }
+            const publicKey = expectReadWithLength(extData.slice(2));
+            return { type, publicKey };
+        }
+    });
+}
+/**
+ * Parse a length-encoded list of extensions
+ * sent by the client
+ */
+export function parseClientExtensions(data) {
+    return parseExtensions(data, {
+        'SERVER_NAME': (extData) => {
+            extData = expectReadWithLength(extData);
+            const byte = extData[0];
+            extData = extData.slice(1);
+            const serverNameBytes = expectReadWithLength(extData);
+            return {
+                type: byte,
+                serverName: uint8ArrayToBinaryStr(serverNameBytes)
+            };
+        }
+    });
+}
+function parseExtensions(data, parsers) {
+    data = readWLength(2);
+    const map = {};
+    const seenExtensions = new Set();
+    while (data.length) {
+        const typeByte = read(2)[1];
+        const extData = readWLength(2);
+        const type = SUPPORTED_EXTENSIONS
+            .find(k => SUPPORTED_EXTENSION_MAP[k] === typeByte);
+        if (seenExtensions.has(typeByte)) {
+            throw new Error(`Duplicate extension '${type}' (${typeByte})`);
+        }
+        if (type && type in parsers) {
+            map[type] = parsers[type](extData);
+        }
+    }
+    return map;
+    function read(bytes) {
+        const result = data.slice(0, bytes);
+        data = data.slice(bytes);
+        return result;
+    }
+    function readWLength(bytesLength = 2) {
+        const content = expectReadWithLength(data, bytesLength);
+        data = data.slice(content.length + bytesLength);
+        return content;
+    }
+}

package/lib/utils/parse-server-hello.d.ts

@@ -0,0 +1,10 @@
+export declare function parseServerHello(data: Uint8Array): Promise<{
+    publicKey?: unknown;
+    publicKeyType?: "X25519" | "SECP256R1" | "SECP384R1" | undefined;
+    serverTlsVersion: "TLS1_3" | "TLS1_2";
+    serverRandom: Uint8Array<ArrayBuffer>;
+    sessionId: Uint8Array<ArrayBuffer>;
+    cipherSuite: "TLS_CHACHA20_POLY1305_SHA256" | "TLS_AES_256_GCM_SHA384" | "TLS_AES_128_GCM_SHA256" | "TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256" | "TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256" | "TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256" | "TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256" | "TLS_RSA_WITH_AES_128_GCM_SHA256" | "TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384" | "TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384" | "TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA" | "TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA";
+    supportsPsk: boolean;
+    extensions: Partial<import("../index.ts").SupportedExtensionServerData>;
+}>;

package/lib/utils/parse-server-hello.js

@@ -0,0 +1,52 @@
+import { crypto } from "../crypto/index.js";
+import { SUPPORTED_CIPHER_SUITE_MAP, SUPPORTED_CIPHER_SUITES, SUPPORTED_NAMED_CURVE_MAP } from "./constants.js";
+import { areUint8ArraysEqual } from "./generics.js";
+import { expectReadWithLength } from "./packets.js";
+import { parseServerExtensions } from "./parse-extensions.js";
+export async function parseServerHello(data) {
+    // header TLS version (expected to be 0x0303)
+    read(2);
+    const serverRandom = read(32);
+    const sessionId = readWLength(1);
+    const cipherSuiteBytes = read(2);
+    const cipherSuite = SUPPORTED_CIPHER_SUITES
+        .find(k => areUint8ArraysEqual(SUPPORTED_CIPHER_SUITE_MAP[k].identifier, cipherSuiteBytes));
+    if (!cipherSuite) {
+        throw new Error(`Unsupported cipher suite '${cipherSuiteBytes}'`);
+    }
+    const compressionMethod = read(1)[0];
+    if (compressionMethod !== 0x00) {
+        throw new Error(`Unsupported compression method '${compressionMethod.toString(16)}'`);
+    }
+    const extensions = parseServerExtensions(data);
+    const serverTlsVersion = extensions['SUPPORTED_VERSIONS'] || 'TLS1_2';
+    const pubKeyExt = extensions['KEY_SHARE'];
+    if (serverTlsVersion === 'TLS1_3'
+        && !pubKeyExt) {
+        throw new Error('Missing key share in TLS 1.3');
+    }
+    return {
+        serverTlsVersion,
+        serverRandom,
+        sessionId,
+        cipherSuite,
+        supportsPsk: !!extensions['PRE_SHARED_KEY']?.supported,
+        extensions,
+        ...(pubKeyExt
+            ? {
+                publicKey: await crypto.importKey(SUPPORTED_NAMED_CURVE_MAP[pubKeyExt.type].algorithm, pubKeyExt.publicKey, 'public'),
+                publicKeyType: pubKeyExt.type,
+            }
+            : {})
+    };
+    function read(bytes) {
+        const result = data.slice(0, bytes);
+        data = data.slice(bytes);
+        return result;
+    }
+    function readWLength(bytesLength = 2) {
+        const content = expectReadWithLength(data, bytesLength);
+        data = data.slice(content.length + bytesLength);
+        return content;
+    }
+}

package/lib/utils/session-ticket.d.ts

@@ -0,0 +1,17 @@
+import type { CipherSuite, TLSSessionTicket } from '../types/index.ts';
+type GetResumableSessionTicketOptions = {
+    masterKey: Uint8Array;
+    /** hello msgs without record header */
+    hellos: Uint8Array[] | Uint8Array;
+    cipherSuite: CipherSuite;
+};
+export declare function parseSessionTicket(data: Uint8Array): TLSSessionTicket;
+export declare function getPskFromTicket(ticket: TLSSessionTicket, { masterKey, hellos, cipherSuite }: GetResumableSessionTicketOptions): Promise<{
+    identity: Uint8Array<ArrayBufferLike>;
+    ticketAge: number;
+    finishKey: unknown;
+    resumeMasterSecret: Uint8Array<ArrayBuffer>;
+    earlySecret: Uint8Array<ArrayBufferLike>;
+    cipherSuite: "TLS_CHACHA20_POLY1305_SHA256" | "TLS_AES_256_GCM_SHA384" | "TLS_AES_128_GCM_SHA256" | "TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256" | "TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256" | "TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256" | "TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256" | "TLS_RSA_WITH_AES_128_GCM_SHA256" | "TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384" | "TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384" | "TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA" | "TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA";
+}>;
+export {};