@typemail/starttls

@typemail/starttls is a very simple library designed for upgrading a net.Socket from cleartext to TLS.

The main usecase for this is the implementation of STARTTLS in various protocols, including SMTP, IMAP, POP3, XMPP, NNTP, IRC, and FTP.

Example

``ts
import { createServer, connect } from 'net';
import { SecureContextOptions, createSecureContext } from 'tls';
import { readFileSync } from 'fs';
import { upgradeSocket } from '@typemail/starttls';

// Load certificates for your server connections.
const secureContext = createSecureContext({
key: readFileSync('./__tests__/cert/server.key'),
cert: readFileSync('./__tests__/cert/server.cert'),
});

const server = createServer(socket => {
// Let's simulate a negotiation, where the server begins it and the client has to accept.
socket.write('STARTTLS', 'ascii', async () => {
socket = await upgradeSocket(socket, {
secureContext,
});

// The socket is now guaranteed to be secure.
// To verify, use isUpgraded() from @typemail/starttls.
// In case of any issues, the Promise will reject.

// Write SECURE to close the socket.
socket.write('SECURE');
});
});

server.listen(2222, '127.0.0.1');

// Client part begins here:
let client = connect({
host: '127.0.0.1',
port: 2222,
});

client.on('data', async data => {
const string = data.toString();
if (string === 'STARTTLS') {
client = await upgradeSocket(client, {
rejectUnauthorized: false,
});

// The socket is now guaranteed to be secure.
// In case of any issues, the Promise will reject.
} else if (string === 'SECURE') {
// We're in a secure socket.
// To verify, use isUpgraded() from @typemail/starttls.
client.destroy();
}
});
`

API

`ts
/**
* Upgrades a regular socket to a TLSSocket.
* @returns Upgraded socket.
*/
function upgradeSocket(
socket: Socket,
options?: TLSSocketOptions
): Promise;

/**
* Determine whether the socket provided is secure or not.
*/
function isUpgraded(socket: Socket): boolean;
``