From 4d5eb1c8111e2517c0fcf90826f1b95af5ad2380 Mon Sep 17 00:00:00 2001
From: wooferguy <tom@cloudspider.com>
Date: Sat, 11 Feb 2023 14:41:19 +1300
Subject: [PATCH] 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         |  7 ++-
 social/email/61-email.html               |  4 ++
 social/email/61-email.js                 |  1 +
 social/email/locales/en-US/61-email.html | 80 ++++++++++++++++--------
 social/email/package.json                |  2 +-
 5 files changed, 63 insertions(+), 31 deletions(-)

diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
index 73563b32..9c8cea7f 100644
--- a/.github/PULL_REQUEST_TEMPLATE.md
+++ b/.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.
-- [ ] I have run `grunt` to verify the unit tests pass
-- [ ] I have added suitable unit tests to cover the new/changed functionality
+- [x] For non-bugfix PRs, I have discussed this change on the forum/slack team.
+- [x] I have run `grunt` to verify the unit tests pass
+- [x] I have added suitable unit tests to cover the new/changed functionality
diff --git a/social/email/61-email.html b/social/email/61-email.html
index f486d896..ac48ddd3 100644
--- a/social/email/61-email.html
+++ b/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();
             }
diff --git a/social/email/61-email.js b/social/email/61-email.js
index 84b4e583..275e90e5 100644
--- a/social/email/61-email.js
+++ b/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;
diff --git a/social/email/locales/en-US/61-email.html b/social/email/locales/en-US/61-email.html
index 3cef9edb..42341059 100644
--- a/social/email/locales/en-US/61-email.html
+++ b/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>
-    <p>The subject is loaded into <code>msg.topic</code> and <code>msg.payload</code> is the plain text body.
-       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
-    <i>to</i>, <i>cc</i> and other potentially useful properties.</p>
-    <p>It can optionally mark the message as Read (default), Delete it, or leave unmarked (None).</p>
-    <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
-        information on the <code>msg.criteria</code> format if needed.</p>
-    <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
-    each object represents a specific attachments.  The format of the object is:</p>
-<pre>
-{
-  contentType:        // The MIME content description
-  fileName:           // A suggested file name associated with this attachment
-  transferEncoding:   // How was the original email attachment encodded?
-  contentDisposition: // Unknown
-  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>
-<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>
-<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>
-<p><b>Note</b>: The maximum refresh interval is 2147483 seconds (24.8 days).</p>
+    <h3>Overview</h3>
+    <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>
+    
+    <h3>Message Properties</h3>
+    <p>The following properties are set on the message object:</p>
+    <ul>
+        <li><code>msg.topic</code> - the subject of the email</li>
+        <li><code>msg.payload</code> - the plain text body of the email</li>
+        <li><code>msg.html</code> - the HTML body of the email (if present)</li>
+        <li><code>msg.from</code> - the sender of the email</li>
+        <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>
+        <li><code>msg.attachments</code> - an array of objects representing any attachments included in the email</li>
+    </ul>
+    
+    <h3>Module Used</h3>
+    <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>
+    
+    <h3>Attachment Format</h3>
+    <p>Each object in the <code>msg.attachments</code> array is formatted as follows:</p>
+    <pre>
+    {
+        contentType:        // The MIME content description
+        fileName:           // A suggested file name associated with this attachment
+        transferEncoding:   // How was the original email attachment encoded?
+        contentDisposition: // Unknown
+        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>
 
diff --git a/social/email/package.json b/social/email/package.json
index 2e362d1a..f71a40cc 100644
--- a/social/email/package.json
+++ b/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",