@joclaim/tls 0.1.0

package/lib/scripts/ca-template.js

@@ -0,0 +1,6 @@
+/* eslint indent: 0 */
+/**
+ * Mozilla Root CA List
+ * downloaded from: https://wiki.mozilla.org/CA/Included_Certificates
+ */
+export const MOZILLA_ROOT_CA_LIST = ['<<CERTIFICATES>>'];

package/lib/scripts/fallbacks/crypto.d.ts

@@ -0,0 +1,4 @@
+import { randomBytes } from '../../crypto/insecure-rand.ts';
+export declare const crypto: {
+    getRandomValues: typeof randomBytes;
+};

package/lib/scripts/fallbacks/crypto.js

@@ -0,0 +1,2 @@
+import { randomBytes } from "../../crypto/insecure-rand.js";
+export const crypto = { getRandomValues: randomBytes };

package/lib/scripts/handshake.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/scripts/handshake.js

@@ -0,0 +1,61 @@
+import { Socket } from 'net';
+import { pino } from 'pino';
+import { makeTLSClient, uint8ArrayToBinaryStr } from "../index.js";
+const LOGGER = pino();
+LOGGER.level = process.env.LOG_LEVEL || 'info';
+const host = readArg('--host');
+if (!host) {
+    console.error('Please provide a host to connect to using --host <hostname>');
+    process.exit(1);
+}
+const port = Number(readArg('--port') || 443);
+const socket = new Socket();
+await new Promise((resolve, reject) => {
+    const tls = makeTLSClient({
+        host,
+        verifyServerCertificate: true,
+        logger: LOGGER,
+        // write raw bytes to the socket
+        write({ header, content }) {
+            socket.write(header);
+            socket.write(content);
+        },
+        async onHandshake() {
+            console.log('handshake completed successfully');
+            await tls.end();
+            socket.end();
+        },
+        onApplicationData(plaintext) {
+            const str = uint8ArrayToBinaryStr(plaintext);
+            console.log('received application data: ', str);
+        },
+        onTlsEnd(error) {
+            if (error) {
+                reject(error);
+                return;
+            }
+            resolve();
+            console.error('TLS connect ended: ', error);
+        }
+    });
+    socket.on('data', tls.handleReceivedBytes);
+    // start handshake as soon as the socket connects
+    socket.once('connect', () => tls.startHandshake());
+    socket.once('error', (err) => reject(err));
+    socket.once('close', () => {
+        console.log('Socket closed');
+        if (!tls.isHandshakeDone()) {
+            reject(new Error('Handshake was not completed before socket closed'));
+        }
+    });
+    // use the TCP socket to connect to the server
+    socket.connect({ host, port });
+});
+console.log(`Connected to ${host} successfully`);
+function readArg(arg) {
+    const index = process.argv.indexOf(arg);
+    if (index === -1) {
+        return undefined;
+    }
+    return process.argv[index + 1] || '';
+}

package/lib/scripts/jsc.d.ts

@@ -0,0 +1,28 @@
+import '../utils/additional-root-cas.js';
+declare global {
+    function readline(): string;
+    function print(...args: any[]): void;
+    function quit(): void;
+    type JscIncomingCmd = {
+        type: 'exit';
+    } | {
+        type: 'send';
+        dataB64: string;
+    } | {
+        type: 'send-application-data';
+        dataB64: string;
+    } | {
+        type: 'connect';
+        host: string;
+        rootCAs?: string[];
+    };
+    type JscOutgoingCmd = {
+        type: 'send-application-data';
+        dataB64: string;
+    } | {
+        type: 'send';
+        dataB64: string;
+    } | {
+        type: 'handshake-done';
+    };
+}

package/lib/scripts/jsc.js

@@ -0,0 +1,92 @@
+// CLI script that can be run via javascriptcore (jsc)
+// used to test that the TLS client works in the pure jsc environment
+// pls build via esbuild first
+import '../utils/additional-root-cas.js';
+import { setCryptoImplementation } from "../crypto/index.js";
+import { pureJsCrypto } from "../crypto/pure-js.js";
+import { makeTLSClient } from "../make-tls-client.js";
+import { concatenateUint8Arrays } from "../utils/generics.js";
+setCryptoImplementation(pureJsCrypto);
+async function main() {
+    print('specify the host to connect to '
+        + '(e.g. {"type":"connect", "host":"localhost:443"}):"}');
+    const initCmd = readCmd();
+    if (initCmd.type !== 'connect') {
+        throw new Error('Expected connect command');
+    }
+    if (initCmd.rootCAs?.length) {
+        TLS_ADDITIONAL_ROOT_CA_LIST.push(...initCmd.rootCAs);
+        print(`Added ${initCmd.rootCAs.length} additional root CAs`);
+    }
+    const tls = makeTLSClient({
+        host: initCmd.host,
+        logger: {
+            info: (...args) => print('[INFO]', ...args),
+            debug: (...args) => print('[DEBUG]', ...args),
+            trace: () => { },
+            warn: (...args) => print('[WARN]', ...args),
+            error: (...args) => print('[ERROR]', ...args),
+        },
+        write({ header, content }) {
+            writeCmd({
+                type: 'send',
+                dataB64: bytesToB64(concatenateUint8Arrays([header, content]))
+            });
+        },
+        onApplicationData(plaintext) {
+            writeCmd({ type: 'send-application-data', dataB64: bytesToB64(plaintext) });
+        },
+        onTlsEnd(error) {
+            print('TLS ended:', error);
+            if (error) {
+                throw error;
+            }
+            quit();
+        },
+        onHandshake() {
+            writeCmd({ type: 'handshake-done' });
+        },
+    });
+    await tls.startHandshake();
+    let cmd;
+    while (cmd = readCmd(), cmd.type !== 'exit') {
+        if (cmd.type === 'send') {
+            const data = base64ToBytes(cmd.dataB64);
+            await tls.handleReceivedBytes(data);
+            continue;
+        }
+        if (cmd.type === 'send-application-data') {
+            const data = base64ToBytes(cmd.dataB64);
+            await tls.write(data);
+            continue;
+        }
+    }
+    print('done ✅');
+}
+function base64ToBytes(b64) {
+    const binary = atob(b64);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) {
+        bytes[i] = binary.charCodeAt(i);
+    }
+    return bytes;
+}
+function bytesToB64(bytes) {
+    let binary = '';
+    for (const byte of bytes) {
+        binary += String.fromCharCode(byte);
+    }
+    return btoa(binary);
+}
+function readCmd() {
+    const cmd = readline();
+    return JSON.parse(cmd);
+}
+function writeCmd(cmd) {
+    print(JSON.stringify(cmd));
+}
+main()
+    .catch(err => {
+    print('error in main fn: ', err.message, '\n', err.stack || err);
+    quit();
+});

package/lib/scripts/update-ca-certs.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/scripts/update-ca-certs.js

@@ -0,0 +1,29 @@
+import { parse } from 'csv-parse/sync';
+import * as fs from 'node:fs';
+import { loadX509FromPem } from "../utils/index.js";
+async function main() {
+    const resp = await fetch('https://ccadb.my.salesforce-sites.com/mozilla/IncludedCACertificateReportPEMCSV');
+    const csv = await resp.text();
+    const records = parse(csv, {
+        columns: true,
+        // eslint-disable-next-line camelcase
+        skip_empty_lines: true
+    });
+    const data = fs.readFileSync('src/scripts/ca-template.ts', 'utf8');
+    let certs = '';
+    for (const record of records) {
+        let pem = record['PEM Info'];
+        pem = pem.slice(1, -1); //remove ' at the beginning and end
+        pem = pem.replaceAll(/\s+\n/sgi, '\n'); //remove trailing spaces in some certs
+        //validate
+        const cert = loadX509FromPem(pem);
+        if (!cert.isWithinValidity()) {
+            throw new Error('certificate is not within validity period');
+        }
+        pem = '`' + pem + '`, //' + record['Common Name or Certificate Name'] + '\n';
+        certs += pem;
+    }
+    const newData = data.replace('\'<<CERTIFICATES>>\'', certs);
+    fs.writeFileSync('src/utils/mozilla-root-cas.ts', Buffer.from(newData));
+}
+main().then();

package/lib/types/crypto.d.ts

@@ -0,0 +1,62 @@
+export type Key = unknown;
+export type AuthenticatedSymmetricCryptoAlgorithm = 'AES-256-GCM' | 'AES-128-GCM' | 'CHACHA20-POLY1305';
+export type SymmetricCryptoAlgorithm = 'AES-128-CBC';
+export type AsymmetricCryptoAlgorithm = 'X25519' | 'P-256' | 'P-384';
+export type AsymmetricEncDecAlgorithm = 'RSA-PCKS1_5';
+export type SignatureAlgorithm = 'RSA-PSS-SHA256' | 'ECDSA-SECP384R1-SHA256' | 'ECDSA-SECP384R1-SHA384' | 'ECDSA-SECP256R1-SHA256' | 'ECDSA-SECP256R1-SHA384' | 'RSA-PKCS1-SHA512' | 'RSA-PKCS1-SHA384' | 'RSA-PKCS1-SHA256' | 'RSA-PKCS1-SHA1';
+export type HashAlgorithm = 'SHA-256' | 'SHA-384' | 'SHA-1';
+type Awaitable<T> = T | Promise<T>;
+type CryptOptions<K = Key> = {
+    key: K;
+    iv: Uint8Array;
+    data: Uint8Array;
+};
+type AuthenticatedCryptOptions<K = Key> = {
+    key: K;
+    iv: Uint8Array;
+    data: Uint8Array;
+    aead: Uint8Array;
+};
+type VerifyOptions<K = Key> = {
+    data: Uint8Array;
+    signature: Uint8Array;
+    publicKey: K;
+};
+export type KeyPair<K = Key> = {
+    pubKey: K;
+    privKey: K;
+};
+export type Crypto<K> = {
+    importKey(alg: AuthenticatedSymmetricCryptoAlgorithm | SymmetricCryptoAlgorithm, raw: Uint8Array, empty?: unknown): Awaitable<K>;
+    importKey(alg: HashAlgorithm, raw: Uint8Array, empty?: unknown): Awaitable<K>;
+    importKey(alg: SignatureAlgorithm | AsymmetricEncDecAlgorithm, raw: Uint8Array, type: 'public'): Awaitable<K>;
+    importKey(alg: AsymmetricCryptoAlgorithm, raw: Uint8Array, type: 'private' | 'public'): Awaitable<K>;
+    exportKey(key: K): Awaitable<Uint8Array>;
+    generateKeyPair(alg: AsymmetricCryptoAlgorithm): Awaitable<KeyPair<K>>;
+    calculateSharedSecret(alg: AsymmetricCryptoAlgorithm, privateKey: K, publicKey: K): Awaitable<Uint8Array>;
+    randomBytes(length: number): Uint8Array;
+    asymmetricEncrypt(cipherSuite: AsymmetricEncDecAlgorithm, opts: {
+        publicKey: K;
+        data: Uint8Array;
+    }): Awaitable<Uint8Array>;
+    /**
+     * Encrypts data with the given cipher suite and options.
+     * Expects padding has already been applied to the data.
+     */
+    encrypt(cipherSuite: SymmetricCryptoAlgorithm, opts: CryptOptions<K>): Awaitable<Uint8Array>;
+    decrypt(cipherSuite: SymmetricCryptoAlgorithm, opts: CryptOptions<K>): Awaitable<Uint8Array>;
+    authenticatedEncrypt(cipherSuite: AuthenticatedSymmetricCryptoAlgorithm, opts: AuthenticatedCryptOptions<K>): Awaitable<{
+        ciphertext: Uint8Array;
+        authTag: Uint8Array;
+    }>;
+    authenticatedDecrypt(cipherSuite: AuthenticatedSymmetricCryptoAlgorithm, opts: AuthenticatedCryptOptions<K> & {
+        authTag: Uint8Array;
+    }): Awaitable<{
+        plaintext: Uint8Array;
+    }>;
+    verify(alg: SignatureAlgorithm, opts: VerifyOptions<K>): Awaitable<boolean>;
+    hash(alg: HashAlgorithm, data: Uint8Array): Awaitable<Uint8Array>;
+    hmac(alg: HashAlgorithm, key: K, data: Uint8Array): Awaitable<Uint8Array>;
+    extract(alg: HashAlgorithm, hashLength: number, ikm: Uint8Array, salt: Uint8Array | string): Awaitable<Uint8Array>;
+};
+export {};

package/lib/types/crypto.js

@@ -0,0 +1 @@
+export {};

package/lib/types/index.d.ts

@@ -0,0 +1,15 @@
+import type { X509Certificate } from './x509.ts';
+export * from './x509.ts';
+export * from './tls.ts';
+export * from './crypto.ts';
+export * from './logger.ts';
+declare global {
+    const TLS_ADDITIONAL_ROOT_CA_LIST: string[];
+    /**
+     * Store fetched intermediate certificates typically fetched via
+     * the AIA extension here to avoid refetching
+     */
+    const TLS_INTERMEDIATE_CA_CACHE: {
+        [url: string]: X509Certificate;
+    };
+}

package/lib/types/index.js

@@ -0,0 +1,4 @@
+export * from "./x509.js";
+export * from "./tls.js";
+export * from "./crypto.js";
+export * from "./logger.js";

package/lib/types/logger.d.ts

@@ -0,0 +1,6 @@
+type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'trace';
+type LogFn = (...args: any[]) => void;
+export type Logger = {
+    [L in LogLevel]: LogFn;
+};
+export {};

package/lib/types/logger.js

@@ -0,0 +1 @@
+export {};

package/lib/types/tls.d.ts

@@ -0,0 +1,141 @@
+import type { CONTENT_TYPE_MAP, SUPPORTED_CIPHER_SUITE_MAP, SUPPORTED_NAMED_CURVE_MAP, SUPPORTED_SIGNATURE_ALGS_MAP, TLS_PROTOCOL_VERSION_MAP } from '../utils/constants.ts';
+import type { Key } from './crypto.ts';
+import type { Logger } from './logger.ts';
+import type { X509Certificate } from './x509.ts';
+export type TLSProtocolVersion = keyof typeof TLS_PROTOCOL_VERSION_MAP;
+export type CipherSuite = keyof typeof SUPPORTED_CIPHER_SUITE_MAP;
+export type TLSPacket = {
+    header: Uint8Array;
+    content: Uint8Array;
+};
+export type TLSKeyType = keyof typeof SUPPORTED_NAMED_CURVE_MAP | 'RSA';
+export type SupportedExtensionServerData = {
+    'ALPN': string;
+    'SUPPORTED_VERSIONS': TLSProtocolVersion;
+    'KEY_SHARE': {
+        type: keyof typeof SUPPORTED_NAMED_CURVE_MAP;
+        publicKey: Uint8Array;
+    };
+    'PRE_SHARED_KEY': {
+        supported: boolean;
+    };
+};
+export type SupportedExtensionClientData = {
+    'SERVER_NAME': {
+        type: number;
+        serverName: string;
+    };
+};
+export type TLSPacketContext = {
+    type: 'plaintext';
+} | {
+    type: 'ciphertext';
+    encKey: Key;
+    /** IV for the session. Computed at handshake */
+    fixedIv: Uint8Array;
+    /** Actual IV used in the cipher process */
+    iv: Uint8Array;
+    macKey?: Key;
+    recordNumber: number;
+    contentType?: keyof typeof CONTENT_TYPE_MAP;
+    /**
+     * Ciphertext of the record
+     * includes the content type,
+     * and authTag/MAC
+     */
+    ciphertext: Uint8Array;
+    plaintext: Uint8Array;
+};
+export type TLSProcessContext = {
+    version: TLSProtocolVersion;
+};
+export type TLSHelloBaseOptions = {
+    /** Only allow connecting via these TLS versions */
+    supportedProtocolVersions?: TLSProtocolVersion[];
+    /** the cipher suites the client will claim it supports */
+    cipherSuites?: (keyof typeof SUPPORTED_CIPHER_SUITE_MAP)[];
+    /** the named curves the client will claim it supports */
+    namedCurves?: (keyof typeof SUPPORTED_NAMED_CURVE_MAP)[];
+    /**
+     * the signature algorithms the client will claim it supports
+     * Only used in TLS 1.3
+     */
+    signatureAlgorithms?: (keyof typeof SUPPORTED_SIGNATURE_ALGS_MAP)[];
+    /**
+     * Write to the application layer protocols extension.
+     * Specify which protocols the client supports
+     */
+    applicationLayerProtocols?: string[];
+};
+export type TLSConnectionOptions = TLSHelloBaseOptions & {
+    /**
+     * if true, an out of band PSK (pre-shared key)
+     * will be generated before connecting via the verifier node
+     * */
+    generateOutOfBandSession?: boolean;
+    /**
+     * if false, the server certificate will not be verified
+     * Use with caution; without server certificate verification
+     * it is super easy to MITM the connection & reveal any secrets
+     */
+    verifyServerCertificate?: boolean;
+    /**
+     * if provided, the server certificate will be verified against these root CAs
+     */
+    rootCAs?: X509Certificate[];
+    /**
+     * Fetch certificate bytes from a URL
+     * Used when the AIA extension is present in a certificate
+     * to fetch the issuer certificate
+     */
+    fetchCertificateBytes?(url: string): Promise<Uint8Array>;
+};
+export type TLSClientOptions = TLSConnectionOptions & TLSEventHandlers & {
+    /** the hostname of the server to connect to */
+    host: string;
+    /**
+     * should it expect the last bytes of a wrapped-record
+     * to have an auth tag
+     * @default true
+     * */
+    expectAuthTagInWrappedRecord?: boolean;
+    logger?: Logger;
+    write(packet: TLSPacket, ctx: TLSPacketContext): Promise<void> | void;
+};
+export type TLSPresharedKey = {
+    identity: Uint8Array;
+    ticketAge: number;
+    finishKey: Key;
+    earlySecret: Uint8Array;
+    cipherSuite: keyof typeof SUPPORTED_CIPHER_SUITE_MAP;
+};
+export type TLSSessionTicket = {
+    expiresAt: Date;
+    lifetimeS: number;
+    ticketAgeAddMs: number;
+    nonce: Uint8Array;
+    ticket: Uint8Array;
+    extensions: Uint8Array;
+};
+export type TLSHandshakeOptions = {
+    random?: Uint8Array;
+    psk?: TLSPresharedKey;
+};
+export type TLSEventHandlers = {
+    onHandshake?(): void;
+    onRecvCertificates?(obj: {
+        certificates: X509Certificate[];
+    }): void;
+    /** Called before any packet is processed */
+    onRead?(packet: TLSPacket, ctx: TLSPacketContext): void;
+    onApplicationData?(plaintext: Uint8Array): void;
+    onTlsEnd?(error?: Error): void;
+    onSessionTicket?(ticket: TLSSessionTicket): void;
+};
+export type TLSPacketWithType = {
+    type: number;
+    packet: TLSPacket;
+};
+export type PacketProcessor = {
+    onData(data: Uint8Array): Generator<TLSPacketWithType>;
+};

package/lib/types/tls.js

@@ -0,0 +1 @@
+export {};

package/lib/types/x509.d.ts

@@ -0,0 +1,32 @@
+export type PrivateKey = string;
+export type CertificatePublicKey = {
+    /**
+     * public key in DER format
+     * DER => Uint8Array
+     */
+    buffer: Uint8Array;
+    algorithm: string;
+};
+export type X509Certificate<T = any> = {
+    internal: T;
+    /**
+     * Checks new Date() is in the validity period
+     * of the certificate, basically outside notBefore and notAfter
+     */
+    isWithinValidity(): boolean;
+    getSubjectField(key: string): string[];
+    getAlternativeDNSNames(): string[];
+    isIssuer(ofCert: X509Certificate<T>): boolean;
+    getPublicKey(): CertificatePublicKey;
+    /**
+     * Get the Authority Information Access extension value,
+     * tells us where to get issuer certificate from
+     */
+    getAIAExtension(): string | undefined;
+    /**
+     * verify this certificate issued the certificate passed
+     * @param otherCert the supposedly issued certificate to verify
+     * */
+    verifyIssued(otherCert: X509Certificate<T>): boolean | Promise<boolean>;
+    serialiseToPem(): string;
+};

package/lib/types/x509.js

@@ -0,0 +1 @@
+export {};

package/lib/utils/additional-root-cas.d.ts

@@ -0,0 +1 @@
+export {};