XOauth2 IMAP Release

Prevent XOAuth2 being used for POP. Update PR Template.
Updated help file.
Bumped version to 1.19-beta

.github/PULL_REQUEST_TEMPLATE.md

@@ -26,11 +26,12 @@ the [forum](https://discourse.nodered.org) or
 <!-- Describe the nature of this change. What problem does it address? -->
 
 Adds authentication option to the Email node (node-red-node-email) to use OAuth and XOAuth2
+********** This version: IMAP ONLY **********
 
 ## Checklist
 <!-- Put an `x` in the boxes that apply -->
 
 - [x] I have read the [contribution guidelines](https://github.com/node-red/node-red-nodes/blob/master/CONTRIBUTING.md)
-- [ ] For non-bugfix PRs, I have discussed this change on the forum/slack team.
+- [x] For non-bugfix PRs, I have discussed this change on the forum/slack team.
-- [ ] I have run `grunt` to verify the unit tests pass
+- [x] I have run `grunt` to verify the unit tests pass
-- [ ] I have added suitable unit tests to cover the new/changed functionality
+- [x] I have added suitable unit tests to cover the new/changed functionality

social/email/61-email.html

@@ -230,6 +230,8 @@
                 $(".node-input-disposition").show();
                 $(".node-input-criteria").show();
             } else {
+                $("#node-input-authtype").val("BASIC");
+                $("#node-input-authtype").change();
                 $(".node-input-autotls").hide();
                 $(".node-input-box").hide();
                 $(".node-input-disposition").hide();
@@ -248,6 +250,8 @@
                 $(".node-input-password").hide();
                 $(".node-input-saslformat").show();
                 $(".node-input-token").show();
+                $("#node-input-protocol").val("IMAP"); //Remove when POP lib updated
+                $("#node-input-protocol").change();
                 $("#node-input-fetch").val("trigger");
                 $("#node-input-fetch").change();
             }

social/email/61-email.js

@@ -204,6 +204,7 @@ module.exports = function(RED) {
         if (this.authtype !== "BASIC") {
             this.inputs = 1;
             this.repeat = 0;
+            this.protocol = "IMAP";
         }
 
         var flag = false;

social/email/locales/en-US/61-email.html

@@ -25,33 +25,59 @@
 </script>
 
 <script type="text/html" data-help-name="e-mail in">
-    <p>Repeatedly gets emails from a POP3 or IMAP server and forwards on as a msg if not already seen.</p>
+    <h3>Overview</h3>
-    <p>The subject is loaded into <code>msg.topic</code> and <code>msg.payload</code> is the plain text body.
+    <p>The e-mail in node retrieves emails from a POP3 or IMAP server and forwards the email data as a message if it has not already been seen.</p>
-       If there is text/html then that is returned in <code>msg.html</code>. <code>msg.from</code> and <code>msg.date</code> are also set if you need them.</p>
+    
-    <p>Additionally <code>msg.header</code> contains the complete header object including
+    <h3>Message Properties</h3>
-    <i>to</i>, <i>cc</i> and other potentially useful properties.</p>
+    <p>The following properties are set on the message object:</p>
-    <p>It can optionally mark the message as Read (default), Delete it, or leave unmarked (None).</p>
+    <ul>
-    <p>Uses the <a href="https://github.com/mscdex/node-imap/blob/master/README.md" target="_new">node-imap module</a> - see that page for
+        <li><code>msg.topic</code> - the subject of the email</li>
-        information on the <code>msg.criteria</code> format if needed.</p>
+        <li><code>msg.payload</code> - the plain text body of the email</li>
-    <p>Any attachments supplied in the incoming email can be found in the <code>msg.attachments</code> property. This will be an array of objects where
+        <li><code>msg.html</code> - the HTML body of the email (if present)</li>
-    each object represents a specific attachments.  The format of the object is:</p>
+        <li><code>msg.from</code> - the sender of the email</li>
-<pre>
+        <li><code>msg.date</code> - the date the email was sent</li>
-{
+        <li><code>msg.header</code> - the complete header object including information such as the "to" and "cc" recipients</li>
-  contentType:        // The MIME content description
+        <li><code>msg.attachments</code> - an array of objects representing any attachments included in the email</li>
-  fileName:           // A suggested file name associated with this attachment
+    </ul>
-  transferEncoding:   // How was the original email attachment encodded?
+    
-  contentDisposition: // Unknown
+    <h3>Module Used</h3>
-  generatedFileName:  // A suggested file name associated with this attachment
+    <p>The e-mail in node uses the <a href="https://github.com/mscdex/node-imap/blob/master/README.md" target="_new">node-imap module</a>, see that page for information on the <code>msg.criteria</code> format if needed.</p>
-  contentId:          // A unique generated ID for this attachment
+    
-  checksum:           // A checksum against the data
+    <h3>Attachment Format</h3>
-  length:             // Size of data in bytes
+    <p>Each object in the <code>msg.attachments</code> array is formatted as follows:</p>
-  content:            // The actual content of the data contained in a Node.js Buffer object
+    <pre>
-                      // We can turn this into a base64 data string with content.toString('base64')
+    {
-}
+        contentType:        // The MIME content description
-</pre>
+        fileName:           // A suggested file name associated with this attachment
-<p><b>Note</b>: For POP3, the default port numbers are 110 for plain TCP and 995 for SSL.  For IMAP the port numbers are 143 for plain TCP and 993 for SSL.</p>
+        transferEncoding:   // How was the original email attachment encoded?
-<p><b>Note</b>: With option 'STARTTLS' an established plain connection is upgraded to an encrypted one. Set to 'always' to always attempt connection upgrades via STARTTLS, 'required' only if upgrading is required, or 'never' to never attempt upgrading.</p>
+        contentDisposition: // Unknown
-<p><b>Note</b>: The maximum refresh interval is 2147483 seconds (24.8 days).</p>
+        generatedFileName:  // A suggested file name associated with this attachment
+        contentId:          // A unique generated ID for this attachment
+        checksum:           // A checksum against the data
+        length:             // Size of data in bytes
+        content:            // The actual content of the data contained in a Node.js Buffer object
+                            // We can turn this into a base64 data string with content.toString('base64')
+    }
+    </pre>
+    <h3>IMAP Authentication</h3>
+    <p>When connecting to an IMAP server, two authentication types are available: Basic and XOAuth2.</p>
+    <ul>
+        <li><b>Basic:</b> requires a username and password to be entered</li>
+        <li><b>XOAuth2:</b> requires a username and a <code>msg</code> property to extract the access token</li>
+    </ul>
+    <p>With XOAuth2 authentication, periodic fetching is not available. The node will only attemp to login when a new token is receieved.</p>
+    <h3>SASL Formatting:</h3>
+    <p>SASL XOAuth2 tokens are created by combining the username and token, encoding it in base64, and passing it to the mail server in the following format:</p>
+    <pre>base64("user=" + userName + "^Aauth=Bearer " + accessToken + "^A^A")</pre>
+    <p>If the checkbox is unticked, flow creators can format the token themselves before passing it to the node.</p>
+
+    <h3>Notes</h3>
+    <ul>
+        <li>For POP3, the default port numbers are 110 for plain TCP and 995 for SSL.  For IMAP the port numbers are 143 for plain TCP and 993 for SSL.</li>
+        <li>With option 'STARTTLS' an established plain connection is upgraded to an encrypted one. Set to 'always' to always attempt connection upgrades via STARTTLS, 'required' only if upgrading is required, or 'never' to never attempt upgrading.</li>
+        <li>The maximum refresh interval is 2147483 seconds (24.8 days).</li>
+        <li>POP XOAuth2 will be supported in future</li>
+    </ul>
 
 </script>
 

social/email/package.json

@@ -1,6 +1,6 @@
 {
   "name": "node-red-node-email",
-  "version": "1.18.4",
+  "version": "1.19.0-beta+xoauth2.imap",
   "description": "Node-RED nodes to send and receive simple emails.",
   "dependencies": {
     "imap": "^0.8.19",