@joclaim/tls 0.1.0

package/lib/utils/session-ticket.js

@@ -0,0 +1,51 @@
+import { crypto } from "../crypto/index.js";
+import { getHash, hkdfExtractAndExpandLabel } from "../utils/decryption-utils.js";
+import { SUPPORTED_CIPHER_SUITE_MAP } from "./constants.js";
+import { uint8ArrayToDataView } from "./generics.js";
+import { expectReadWithLength } from "./packets.js";
+export function parseSessionTicket(data) {
+    const lifetimeS = read(4).getUint32(0);
+    const ticketAgeAddMs = read(4).getUint32(0);
+    const nonce = readWLength(1);
+    const ticket = readWLength(2);
+    const extensions = readWLength(2);
+    const sessionTicket = {
+        ticket,
+        lifetimeS,
+        ticketAgeAddMs,
+        nonce,
+        expiresAt: new Date(Date.now() + lifetimeS * 1000),
+        extensions
+    };
+    return sessionTicket;
+    function read(bytes) {
+        const result = data.slice(0, bytes);
+        data = data.slice(bytes);
+        return uint8ArrayToDataView(result);
+    }
+    function readWLength(bytesLength = 2) {
+        const content = expectReadWithLength(data, bytesLength);
+        data = data.slice(content.length + bytesLength);
+        return content;
+    }
+}
+export async function getPskFromTicket(ticket, { masterKey, hellos, cipherSuite }) {
+    const { hashAlgorithm, hashLength } = SUPPORTED_CIPHER_SUITE_MAP[cipherSuite];
+    const handshakeHash = await getHash(hellos, cipherSuite);
+    const resumeMasterSecret = await hkdfExtractAndExpandLabel(hashAlgorithm, masterKey, 'res master', handshakeHash, hashLength);
+    const psk = await hkdfExtractAndExpandLabel(hashAlgorithm, resumeMasterSecret, 'resumption', ticket.nonce, hashLength);
+    const emptyHash = await crypto.hash(hashAlgorithm, new Uint8Array());
+    const earlySecret = await crypto.extract(hashAlgorithm, hashLength, psk, '');
+    const binderKey = await hkdfExtractAndExpandLabel(hashAlgorithm, earlySecret, 'res binder', emptyHash, hashLength);
+    // const clientEarlyTrafficSecret = hkdfExtractAndExpandLabel(hashAlgorithm, earlySecret, 'c e traffic', new Uint8Array(), hashLength)
+    const finishKey = await hkdfExtractAndExpandLabel(hashAlgorithm, binderKey, 'finished', new Uint8Array(), hashLength);
+    const ticketAge = Math.floor(ticket.lifetimeS / 1000 + ticket.ticketAgeAddMs);
+    return {
+        identity: ticket.ticket,
+        ticketAge,
+        finishKey: await crypto.importKey(hashAlgorithm, finishKey),
+        resumeMasterSecret,
+        earlySecret,
+        cipherSuite,
+    };
+}

package/lib/utils/wrapped-record.d.ts

@@ -0,0 +1,25 @@
+import type { CipherSuite, Key, TLSProtocolVersion } from '../types/index.ts';
+import type { PacketHeaderOptions } from './packets.ts';
+type WrappedRecordMacGenOptions = {
+    macKey?: Key;
+    recordNumber: number | undefined;
+    cipherSuite: CipherSuite;
+    version: TLSProtocolVersion;
+} & ({
+    recordHeaderOpts: PacketHeaderOptions;
+} | {
+    recordHeader: Uint8Array;
+});
+type WrappedRecordCipherOptions = {
+    iv: Uint8Array;
+    key: Key;
+} & WrappedRecordMacGenOptions;
+export declare function decryptWrappedRecord(encryptedData: Uint8Array, opts: WrappedRecordCipherOptions): Promise<{
+    plaintext: Uint8Array<ArrayBufferLike>;
+    iv: Uint8Array<ArrayBufferLike>;
+}>;
+export declare function encryptWrappedRecord(plaintext: Uint8Array, opts: WrappedRecordCipherOptions): Promise<{
+    ciphertext: Uint8Array<ArrayBufferLike>;
+    iv: Uint8Array<ArrayBufferLike>;
+}>;
+export {};

package/lib/utils/wrapped-record.js

@@ -0,0 +1,191 @@
+import { crypto } from "../crypto/index.js";
+import { AUTH_TAG_BYTE_LENGTH, SUPPORTED_CIPHER_SUITE_MAP } from "./constants.js";
+import { areUint8ArraysEqual, concatenateUint8Arrays, generateIV, isSymmetricCipher, padTls, toHexStringWithWhitespace, uint8ArrayToDataView, unpadTls } from "./generics.js";
+import { packPacketHeader } from "./packets.js";
+const AUTH_CIPHER_LENGTH = 12;
+export async function decryptWrappedRecord(encryptedData, opts) {
+    if (!('recordHeader' in opts)) {
+        throw new Error('recordHeader is required for decrypt');
+    }
+    const { key, recordNumber, cipherSuite, } = opts;
+    const { cipher, hashLength } = SUPPORTED_CIPHER_SUITE_MAP[cipherSuite];
+    return isSymmetricCipher(cipher)
+        ? doCipherDecrypt(cipher)
+        : doAuthCipherDecrypt(cipher);
+    async function doCipherDecrypt(cipher) {
+        const iv = encryptedData.slice(0, 16);
+        const ciphertext = encryptedData.slice(16);
+        let plaintextAndMac = await crypto.decrypt(cipher, {
+            key,
+            iv,
+            data: ciphertext,
+        });
+        plaintextAndMac = unpadTls(plaintextAndMac);
+        plaintextAndMac = plaintextAndMac.slice(0, -1);
+        const mac = plaintextAndMac.slice(-hashLength);
+        const plaintext = plaintextAndMac.slice(0, -hashLength);
+        const macComputed = await computeMacTls12(plaintext, opts);
+        if (!areUint8ArraysEqual(mac, macComputed)) {
+            throw new Error(`MAC mismatch: expected ${toHexStringWithWhitespace(macComputed)}, got ${toHexStringWithWhitespace(mac)}`);
+        }
+        return { plaintext, iv };
+    }
+    async function doAuthCipherDecrypt(cipher) {
+        let iv = opts.iv;
+        const recordIvLength = AUTH_CIPHER_LENGTH - iv.length;
+        if (recordIvLength) {
+            // const recordIv = new Uint8Array(recordIvLength)
+            // const seqNumberView = uint8ArrayToDataView(recordIv)
+            // seqNumberView.setUint32(recordIvLength - 4, recordNumber)
+            const recordIv = encryptedData.slice(0, recordIvLength);
+            encryptedData = encryptedData.slice(recordIvLength);
+            iv = concatenateUint8Arrays([
+                iv,
+                recordIv
+            ]);
+        }
+        else if (
+        // use IV generation alg for TLS 1.3
+        // and ChaCha20-Poly1305
+        (opts.version === 'TLS1_3'
+            || cipher === 'CHACHA20-POLY1305') && typeof recordNumber !== 'undefined') {
+            iv = generateIV(iv, recordNumber);
+        }
+        const authTag = encryptedData.slice(-AUTH_TAG_BYTE_LENGTH);
+        encryptedData = encryptedData.slice(0, -AUTH_TAG_BYTE_LENGTH);
+        const aead = getAead(encryptedData.length, opts);
+        const { plaintext } = await crypto.authenticatedDecrypt(cipher, {
+            key,
+            iv,
+            data: encryptedData,
+            aead,
+            authTag,
+        });
+        if (plaintext.length !== encryptedData.length) {
+            throw new Error('Decrypted length does not match encrypted length');
+        }
+        return { plaintext, iv };
+    }
+}
+export async function encryptWrappedRecord(plaintext, opts) {
+    const { key, recordNumber, cipherSuite, } = opts;
+    const { cipher } = SUPPORTED_CIPHER_SUITE_MAP[cipherSuite];
+    let iv = opts.iv;
+    return isSymmetricCipher(cipher)
+        ? doSymmetricEncrypt(cipher)
+        : doAuthSymmetricEncrypt(cipher);
+    async function doAuthSymmetricEncrypt(cipher) {
+        const aead = getAead(plaintext.length, opts);
+        // record IV is the record number as a 64-bit big-endian integer
+        const recordIvLength = AUTH_CIPHER_LENGTH - iv.length;
+        let recordIv;
+        let completeIv = iv;
+        if (recordIvLength && typeof recordNumber !== 'undefined') {
+            recordIv = new Uint8Array(recordIvLength);
+            const seqNumberView = uint8ArrayToDataView(recordIv);
+            seqNumberView.setUint32(recordIvLength - 4, recordNumber);
+            completeIv = concatenateUint8Arrays([
+                iv,
+                recordIv
+            ]);
+        }
+        else if (
+        // use IV generation alg for TLS 1.3
+        // and ChaCha20-Poly1305
+        (opts.version === 'TLS1_3'
+            || cipher === 'CHACHA20-POLY1305')
+            && typeof recordNumber !== 'undefined') {
+            completeIv = generateIV(completeIv, recordNumber);
+        }
+        const enc = await crypto.authenticatedEncrypt(cipher, {
+            key,
+            iv: completeIv,
+            data: plaintext,
+            aead,
+        });
+        if (recordIv) {
+            enc.ciphertext = concatenateUint8Arrays([
+                recordIv,
+                enc.ciphertext,
+            ]);
+        }
+        return {
+            ciphertext: concatenateUint8Arrays([
+                enc.ciphertext,
+                enc.authTag,
+            ]),
+            iv: completeIv
+        };
+    }
+    async function doSymmetricEncrypt(cipher) {
+        const blockSize = 16;
+        iv = padBytes(opts.iv, 16).slice(0, 16);
+        const mac = await computeMacTls12(plaintext, opts);
+        const completeData = concatenateUint8Arrays([
+            plaintext,
+            mac,
+        ]);
+        // add TLS's special padding :(
+        const padded = padTls(completeData, blockSize);
+        const result = await crypto.encrypt(cipher, { key, iv, data: padded });
+        return {
+            ciphertext: concatenateUint8Arrays([
+                iv,
+                result
+            ]),
+            iv,
+        };
+    }
+    function padBytes(arr, len) {
+        const returnVal = new Uint8Array(len);
+        returnVal.set(arr, len - arr.length);
+        return returnVal;
+    }
+}
+function getAead(plaintextLength, opts) {
+    const isTls13 = opts.version === 'TLS1_3';
+    let aead;
+    if (isTls13) {
+        const dataLen = plaintextLength + AUTH_TAG_BYTE_LENGTH;
+        const recordHeader = 'recordHeaderOpts' in opts
+            ? packPacketHeader(dataLen, opts.recordHeaderOpts)
+            : replaceRecordHeaderLen(opts.recordHeader, dataLen);
+        aead = recordHeader;
+    }
+    else {
+        aead = getTls12Header(plaintextLength, opts);
+    }
+    return aead;
+}
+function getTls12Header(plaintextLength, opts) {
+    const { recordNumber } = opts;
+    const recordHeader = 'recordHeaderOpts' in opts
+        ? packPacketHeader(plaintextLength, opts.recordHeaderOpts)
+        : replaceRecordHeaderLen(opts.recordHeader, plaintextLength);
+    const seqNumberBytes = new Uint8Array(8);
+    const seqNumberView = uint8ArrayToDataView(seqNumberBytes);
+    seqNumberView.setUint32(4, recordNumber || 0);
+    return concatenateUint8Arrays([
+        seqNumberBytes,
+        recordHeader,
+    ]);
+}
+async function computeMacTls12(plaintext, opts) {
+    const { macKey, cipherSuite } = opts;
+    if (!macKey) {
+        throw new Error('macKey is required for non-AEAD cipher');
+    }
+    const { hashAlgorithm } = SUPPORTED_CIPHER_SUITE_MAP[cipherSuite];
+    const dataToSign = concatenateUint8Arrays([
+        getTls12Header(plaintext.length, opts),
+        plaintext,
+    ]);
+    const mac = await crypto.hmac(hashAlgorithm, macKey, dataToSign);
+    return mac;
+}
+function replaceRecordHeaderLen(header, newLength) {
+    const newRecordHeader = new Uint8Array(header);
+    const dataView = uint8ArrayToDataView(newRecordHeader);
+    dataView.setUint16(3, newLength);
+    return newRecordHeader;
+}

package/lib/utils/x509.d.ts

@@ -0,0 +1,5 @@
+import * as peculiar from '@peculiar/x509';
+import type { X509Certificate } from '../types/index.ts';
+export declare function loadX509FromPem(pem: string | Uint8Array): X509Certificate<peculiar.X509Certificate>;
+export declare function loadX509FromDer(der: Uint8Array): X509Certificate<peculiar.X509Certificate>;
+export declare function defaultFetchCertificateBytes(url: string): Promise<Uint8Array<any>>;

package/lib/utils/x509.js

@@ -0,0 +1,124 @@
+import * as peculiar from '@peculiar/x509';
+import { SubjectAlternativeNameExtension } from '@peculiar/x509';
+import { crypto } from "../crypto/index.js";
+const AIA_EXT_TYPE = '1.3.6.1.5.5.7.1.1';
+export function loadX509FromPem(pem) {
+    let cert;
+    try {
+        cert = new peculiar.X509Certificate(pem);
+    }
+    catch (e) {
+        throw new Error(`Unsupported certificate: ${e}`);
+    }
+    return {
+        internal: cert,
+        isWithinValidity() {
+            const now = new Date();
+            return now > cert.notBefore && now < cert.notAfter;
+        },
+        getAIAExtension() {
+            const aiaExt = cert
+                .getExtension(AIA_EXT_TYPE);
+            return aiaExt?.caIssuers?.find(obj => obj.type === 'url')?.value;
+        },
+        getSubjectField(name) {
+            return cert.subjectName.getField(name);
+        },
+        getAlternativeDNSNames() {
+            // search for names in SubjectAlternativeNameExtension
+            const ext = cert.extensions
+                .find(e => e.type === '2.5.29.17'); //subjectAltName
+            if (ext instanceof SubjectAlternativeNameExtension) {
+                return ext.names.items
+                    .filter(n => n.type === 'dns')
+                    .map(n => n.value);
+            }
+            return [];
+        },
+        isIssuer({ internal: ofCert }) {
+            var i = ofCert.issuer;
+            var s = cert.subject;
+            return i === s;
+        },
+        getPublicKey() {
+            return {
+                buffer: new Uint8Array(cert.publicKey.rawData),
+                algorithm: cert.publicKey.algorithm.name,
+            };
+        },
+        async verifyIssued(otherCert) {
+            const sigAlg = getSigAlgorithm(cert.publicKey, otherCert.internal);
+            const impPublicKey = await crypto
+                .importKey(sigAlg, new Uint8Array(cert.publicKey.rawData), 'public');
+            const signature = new Uint8Array(otherCert.internal.signature);
+            const verified = await crypto.verify(sigAlg, {
+                publicKey: impPublicKey,
+                signature,
+                data: new Uint8Array(otherCert.internal['tbs'])
+            });
+            return verified;
+        },
+        serialiseToPem() {
+            return cert.toString('pem');
+        },
+    };
+}
+function getSigAlgorithm(key, { signatureAlgorithm }) {
+    if (!('name' in signatureAlgorithm)) {
+        throw new Error('Missing signature algorithm name');
+    }
+    const { name, hash } = signatureAlgorithm;
+    const { algorithm: keyAlg } = key;
+    if (keyAlg.name !== name) {
+        throw new Error(`Signature algorithm ${name} does not match`
+            + ` public key algorithm ${keyAlg.name}`);
+    }
+    let hashName;
+    switch (hash.name) {
+        case 'SHA-256':
+            hashName = 'SHA256';
+            break;
+        case 'SHA-384':
+            hashName = 'SHA384';
+            break;
+        case 'SHA-512':
+            hashName = 'SHA512';
+            break;
+        case 'SHA-1':
+            hashName = 'SHA1';
+            break;
+        default:
+            throw new Error(`Unsupported hash algorithm: ${hash.name}`);
+    }
+    switch (name) {
+        case 'RSASSA-PKCS1-v1_5':
+        case 'RSA-PKCS1-SHA1':
+            return `RSA-PKCS1-${hashName}`;
+        case 'ECDSA':
+            if (hashName === 'SHA512' || hashName === 'SHA1') {
+                throw new Error(`Unsupported hash algorithm for ECDSA: ${hashName}`);
+            }
+            switch (keyAlg.namedCurve) {
+                case 'P-256':
+                    return `ECDSA-SECP256R1-${hashName}`;
+                case 'P-384':
+                    return `ECDSA-SECP384R1-${hashName}`;
+                default:
+                    throw new Error(`Unsupported named curve: ${keyAlg.namedCurve}`);
+            }
+        default:
+            throw new Error(`Unsupported signature algorithm: ${name}`);
+    }
+}
+export function loadX509FromDer(der) {
+    // peculiar handles both
+    return loadX509FromPem(der);
+}
+export async function defaultFetchCertificateBytes(url) {
+    const res = await fetch(url);
+    if (!res.ok) {
+        throw new Error(`Failed to fetch certificate from ${url}: ${res.statusText}`);
+    }
+    const buffer = await res.arrayBuffer();
+    return new Uint8Array(buffer);
+}

package/package.json

@@ -0,0 +1,82 @@
+{
+	"name": "@joclaim/tls",
+	"version": "0.1.0",
+	"description": "TLS 1.2/1.3 for any JavaScript Environment",
+	"type": "module",
+	"exports": {
+		".": {
+			"types": "./lib/index.d.ts",
+			"default": "./lib/index.js"
+		},
+		"./webcrypto": {
+			"types": "./lib/crypto/webcrypto.d.ts",
+			"default": "./lib/crypto/webcrypto.js"
+		},
+		"./purejs-crypto": {
+			"types": "./lib/crypto/pure-js.d.ts",
+			"default": "./lib/crypto/pure-js.js"
+		}
+	},
+	"scripts": {
+		"build": "npm exec tsc -- -p tsconfig.build.json",
+		"build:jsc": "npm run run:tsc src/scripts/build-jsc.ts",
+		"run:tsc": "node --experimental-strip-types",
+		"test:pure-js": "npm run run:tsc -- --import=./src/tests/load-purejs-crypto.ts --test",
+		"test:webcrypto": "npm run run:tsc -- --import=./src/tests/load-webcrypto.ts --test",
+		"handshake": "npm run run:tsc -- --import=./src/tests/load-webcrypto.ts ./src/scripts/handshake.ts",
+		"lint": "eslint . --ext .js,.ts,.jsx,.tsx",
+		"lint:fix": "eslint . --fix --ext .js,.ts,.jsx,.tsx",
+		"prepare": "npm run build",
+		"commitlint": "commitlint --edit",
+		"update:root-ca": "npm run run:tsc -- src/scripts/update-ca-certs.ts"
+	},
+	"keywords": [
+		"tls",
+		"webcrypto",
+		"cross-platform",
+		"cryptography",
+		"network-security",
+		"encryption",
+		"reclaim-protocol",
+		"asn1",
+		"x509",
+		"chacha20poly1305",
+		"typescript",
+		"nodejs",
+		"web-security",
+		"certificate-handling",
+		"secure-communication"
+	],
+	"author": "Adhiraj Singh",
+	"license": "See License in <https://github.com/reclaimprotocol/.github/blob/main/LICENSE>",
+	"bugs": {
+		"url": "https://github.com/reclaimprotocol/tls/issues"
+	},
+	"homepage": "https://github.com/reclaimprotocol/tls/",
+	"files": [
+		"lib/*"
+	],
+	"dependencies": {
+		"@noble/ciphers": "^1.3.0",
+		"@noble/curves": "^1.9.6",
+		"@noble/hashes": "^1.8.0",
+		"@peculiar/asn1-ecc": "^2.3.14",
+		"@peculiar/asn1-schema": "^2.3.13",
+		"@peculiar/x509": "^1.12.3",
+		"micro-rsa-dsa-dh": "^0.1.0"
+	},
+	"devDependencies": {
+		"@adiwajshing/eslint-config": "github:adiwajshing/eslint-config",
+		"@commitlint/cli": "^17.8.1",
+		"@commitlint/config-conventional": "^17.8.1",
+		"@types/chance": "^1.1.6",
+		"@types/node": "^22.0.0",
+		"@typescript-eslint/eslint-plugin": "^8.17.0",
+		"chance": "^1.1.12",
+		"csv-parse": "^5.6.0",
+		"esbuild": "^0.25.8",
+		"eslint": "^8.57.1",
+		"pino": "^9.5.0",
+		"typescript": "^5.9.2"
+	}
+}