Expose new tlsMode and tlsVerify options for connecting to the mail submission agent (#134)

* Expose new `tlsMode` and `tlsVerify` options for connecting to the mail submission agent

* Make `tlsVerify` default to opportunistic StartTLS on ports other than 465 to prevent breaking change

---------

Co-authored-by: Bruno Bernardino <me@brunobernardino.com>

.env.sample

@@ -16,5 +16,5 @@ MFA_SALT="fake" # optional, if you want to enable multi-factor authentication
 OIDC_CLIENT_ID="fake" # optional, if you want to enable SSO (Single Sign-On)
 OIDC_CLIENT_SECRET="fake" # optional, if you want to enable SSO (Single Sign-On)
 
-SMTP_USERNAME="fake" # optional, if you want to enable signup email verification or multi-factor authentication via email
-SMTP_PASSWORD="fake" # optional, if you want to enable signup email verification or multi-factor authentication via email
+#SMTP_USERNAME=""  # optional, if you want to use signup email verification or multi-factor with an email service requiring authentication
+#SMTP_PASSWORD=""  # optional, if you want to use signup email verification or multi-factor with an email service requiring authentication

bewcloud.config.sample.ts

@@ -32,6 +32,8 @@ const config: PartialDeep<Config> = {
   //   from: 'help@bewcloud.com',
   //   host: 'localhost',
   //   port: 465,
+  //   tlsMode: "auto",  // “auto” means “immediate” on port 465, “starttls” otherwise; `null` is legacy behaviour that will be removed in v4: on port 465 it also means “immediate”, otherwise it will use opportunistic StartTLS falling back to plain transmission
+  //   tlsVerify: true,  // Whether to verify the TLS certificate. If a string is used the hostname will be verified using that name.
   // },
   // contacts: {
   //   enableCardDavServer: true,

lib/config.ts

@@ -37,6 +37,8 @@ export class AppConfig {
         from: 'help@bewcloud.com',
         host: 'localhost',
         port: 465,
+        tlsMode: null,
+        tlsVerify: true,
       },
       contacts: {
         enableCardDavServer: true,
@@ -97,6 +99,10 @@ export class AppConfig {
 
       console.info('\nConfig loaded from bewcloud.config.ts', JSON.stringify(this.config, null, 2), '\n');
 
+      if (this.config.email.port !== 465 && this.config.email.tlsMode === null) {
+        console.warn("DEPRECATION WARNING: When using `config.email.port` with a value other than `465`, please set `config.email.tlsMode` to either `'starttls'` or `'none'` to explicitly enable or disable usage of StartTLS! Support for legacy opportunistic StartTLS will be removed in bewCloud 4!");
+      }
+
       if (this.config.core.enabledApps.length === 0) {
         throw new Error('At least one app must be enabled. Please check the config.core.enabledApps array.');
       }

lib/models/email.ts

@@ -15,14 +15,31 @@ export class EmailModel {
       throw new Error('config.email.from, config.email.host, or config.email.port is not set');
     }
 
+    let tlsMode = emailConfig.tlsMode;
+    if (tlsMode === null) {
+      // Value “default” will be ignored below causing the nodemailer default behaviour of using opportunistic StartTLS
+      tlsMode = Number(emailConfig.port) === 465 ? "immediate" : "default";
+    } else if (!["immediate", "starttls", "none"].includes(tlsMode)) {
+      tlsMode = Number(emailConfig.port) === 465 ? "immediate" : "starttls";
+    }
+
     const transporterConfig = {
       host: emailConfig.host,
       port: emailConfig.port,
-      secure: Number(emailConfig.port) === 465,
-      auth: {
+
+      secure: tlsMode === "immediate",
+      requireTLS: tlsMode === "starttls",
+      ignoreTLS: tlsMode === "none",
+      tls: (
+        emailConfig.tlsVerify === false ? { rejectUnauthorized: false } :
+        emailConfig.tlsVerify !== true  ? { servername: emailConfig.tlsVerify } :
+        {}
+      ),
+
+      auth: (SMTP_USERNAME || SMTP_PASSWORD) ? {
         user: SMTP_USERNAME,
         pass: SMTP_PASSWORD,
-      },
+      } : null,
     };
 
     const transporter = nodemailer.createTransport(transporterConfig);

lib/types.ts

@@ -206,6 +206,10 @@ export interface Config {
     host: string;
     /** The SMTP port to send emails from */
     port: number;
+    /** “auto” means “immediate” on port 465, “starttls” otherwise; `null` is legacy behaviour that will be removed in v4: on port 465 it also means “immediate”, otherwise it will use opportunistic StartTLS falling back to plain transmission */
+    tlsMode: null | "auto" | "immediate" | "starttls" | "none";
+    /** Whether to verify the TLS certificate. If a string is used the hostname will be verified using that name. */
+    tlsVerify: boolean | string;
   };
   contacts: {
     /** If true, the CardDAV server will be enabled (proxied) */