notifications-node-client - npm Package Compare versions

Comparing version 5.1.2 to 5.2.0

CHANGELOG.md

@@ -0,4 +1,13 @@
+## 5.2.0 - 2022-09-27
+
+* Add support for new security features when sending a file by email:
+  * `confirmEmailBeforeDownload` can be set to `true` to require the user to enter their email address before accessing the file.
+  * `retentionPeriod` can be set to `<1-78> weeks` to set how long the file should be made available.
+
+* The `isCsv` parameter to `prepareUpload` has now been replaced by an `options` parameter. The implementation has been done in a backwards-compatible way, so if you are just sending `true/false` values as the seecond parameter, that will continue to work. Though we still recommend updating to use the new options format.
+
+
 ## 5.1.2 - 2022-09-23
 
-Remove underscore.js dependency
+Remove underscore.js dependencyr new send a file features)
 
@@ -5,0 +14,0 @@ ## 5.1.1 - 2022-01-18

client/notification.js

@@ -347,11 +347,29 @@ var ApiClient = require('./api_client');
   * @param {Buffer} fileData
-  * @param {Boolean} isCsv
+  * @param {object} options
   *
   * @returns {Dictionary}
   */
-  prepareUpload: function(fileData, isCsv = false) {
-    return {
-      'file': _check_and_encode_file(fileData, 2),
-      'is_csv': isCsv
+  prepareUpload: function(fileData, options) {
+    let data = {
+      file: _check_and_encode_file(fileData, 2),
+      is_csv: false,
+      confirm_email_before_download: null,
+      retention_period: null,
     }
+
+    if (options !== undefined) {
+      if (typeof(options) === 'boolean') {
+        data.is_csv = options
+      }
+      else {
+        if (options.isCsv !== undefined) {
+          data.is_csv = options.isCsv;
+        }
+
+        data.confirm_email_before_download = options.confirmEmailBeforeDownload || null;
+        data.retention_period = options.retentionPeriod || null
+      }
+    }
+
+    return data
   },
@@ -358,0 +376,0 @@

DOCUMENTATION.md

@@ -292,6 +292,13 @@ # Node.js client documentation
 
-The file will be available for the recipient to download for 18 months.
-
 The links are unique and unguessable. GOV.UK Notify cannot access or decrypt your file.
 
+Your file will be available to download for a default period of 78 weeks (18 months). From 29 March 2023 we will reduce this to 26 weeks (6 months) for all new files. Files sent before 29 March will not be affected.
+
+To help protect your files you can also:
+
+* ask recipients to confirm their email address before downloading
+* choose the length of time that a file is available to download
+
+To turn these features on or off, you will need version 5.2.0 of the Node.js client library or a more recent version.
+
 #### Add contact details to the file download page
@@ -309,5 +316,5 @@
 1. Select __Edit__.
-1. Add a placeholder to the email template using double brackets. For example:
+1. Add a placeholder to the email template using double brackets. For example: "Download your file at: ((link_to_file))"
 
-"Download your file at: ((link_to_file))"
+Your email should also tell recipients how long the file will be available to download.
 
@@ -359,2 +366,87 @@ #### Upload your file
 
+#### Ask recipients to confirm their email address before they can download the file
+
+This new security feature is optional. You should use it if you send files that are sensitive - for example, because they contain personal information about your users.
+
+When a recipient clicks the link in the email you’ve sent them, they have to enter their email address. Only someone who knows the recipient’s email address can download the file.
+
+From 29 March 2023, we will turn this feature on by default for every file you send. Files sent before 29 March will not be affected.
+
+##### Turn on email address check
+
+To use this feature before 29 March 2023 you will need version 5.2.0 of the Node.js client library, or a more recent version.
+
+To make the recipient confirm their email address before downloading the file, set the `confirmEmailBeforeDownload` flag to `true`.
+
+You will not need to do this after 29 March.
+
+```javascript
+var fs = require('fs')
+
+fs.readFile('path/to/document.pdf', function (err, pdfFile) {
+  console.log(err)
+  notifyClient.sendEmail(templateId, emailAddress, {
+    personalisation: {
+      first_name: 'Amala',
+      application_date: '2018-01-01',
+      link_to_file: notifyClient.prepareUpload(pdfFile, false, true, undefined)
+    }
+  }).then(response => console.log(response)).catch(err => console.error(err))
+})
+```
+
+##### Turn off email address check (not recommended)
+
+If you do not want to use this feature after 29 March 2023, you can turn it off on a file-by-file basis.
+
+To do this you will need version 5.2.0 of the Node.js client library, or a more recent version.
+
+You should not turn this feature off if you send files that contain:
+
+* personally identifiable information
+* commercially sensitive information
+* information classified as ‘OFFICIAL’ or ‘OFFICIAL-SENSITIVE’ under the [Government Security Classifications](https://www.gov.uk/government/publications/government-security-classifications) policy
+
+To let the recipient download the file without confirming their email address, set the `confirmEmailBeforeDownload` flag to `false`.
+
+```javascript
+var fs = require('fs')
+
+fs.readFile('path/to/document.pdf', function (err, pdfFile) {
+  console.log(err)
+  notifyClient.sendEmail(templateId, emailAddress, {
+    personalisation: {
+      first_name: 'Amala',
+      application_date: '2018-01-01',
+      link_to_file: notifyClient.prepareUpload(pdfFile, false, false, undefined)
+    }
+  }).then(response => console.log(response)).catch(err => console.error(err))
+})
+```
+
+#### Choose the length of time that a file is available to download
+
+Set the number of weeks you want the file to be available using the `retentionPeriod` parameter.
+
+You can choose any value between 1 week and 78 weeks.
+
+To use this feature will need version 5.2.0 of the Node.js client library, or a more recent version.
+
+If you do not choose a value, the file will be available for the default period of 78 weeks (18 months).
+
+```javascript
+var fs = require('fs')
+
+fs.readFile('path/to/document.pdf', function (err, pdfFile) {
+  console.log(err)
+  notifyClient.sendEmail(templateId, emailAddress, {
+    personalisation: {
+      first_name: 'Amala',
+      application_date: '2018-01-01',
+      link_to_file: notifyClient.prepareUpload(pdfFile, false, undefined, '52 weeks')
+    }
+  }).then(response => console.log(response)).catch(err => console.error(err))
+})
+```
+
 #### Response
@@ -391,2 +483,4 @@
 |`400`|`[{`<br>`"error": "BadRequestError",`<br>`"message": "Unsupported file type '(FILE TYPE)'. Supported types are: '(ALLOWED TYPES)'"`<br>`}]`|Wrong file type. You can only upload .pdf, .csv, .txt, .doc, .docx, .xlsx, .rtf or .odt files|
+|`400`|`[{`<br>`"error": "BadRequestError",`<br>`"message": "Unsupported value for retention_period '(PERIOD)'. Supported periods are from 1 to 78 weeks."`<br>`}]`|Choose a period between 1 and 78 weeks|
+|`400`|`[{`<br>`"error": "BadRequestError",`<br>`"message": "Unsupported value for confirm_email_before_download: '(VALUE)'. Use a boolean true or false value."`<br>`}]`|Use either true or false|
 |`400`|`[{`<br>`"error": "BadRequestError",`<br>`"message": "File did not pass the virus scan"`<br>`}]`|The file contains a virus|
@@ -393,0 +487,0 @@ |`400`|`[{`<br>`"error": "BadRequestError",`<br>`"message": "Send files by email has not been set up - add contact details for your service at https://www.notifications.service.gov.uk/services/(SERVICE ID)/service-settings/send-files-by-email"`<br>`}]`|See how to [add contact details to the file download page](#add-contact-details-to-the-file-download-page)|

package.json

 {
   "name": "notifications-node-client",
-  "version": "5.1.2",
+  "version": "5.2.0",
   "homepage": "https://docs.notifications.service.gov.uk/node.html",
@@ -5,0 +5,0 @@ "repository": {

spec/notification.js

@@ -191,2 +191,37 @@ const chai = require('chai');
     });
+
+    it('should allow isCsv to be set with the old method (directly into options)', () => {
+      let file = Buffer.alloc(2*1024*1024)
+      expect(
+        notifyClient.prepareUpload(file, true)
+      ).contains({is_csv: true, confirm_email_before_download: null, retention_period: null})
+    });
+
+    it('should allow isCsv to be set as part of the options object', () => {
+      let file = Buffer.alloc(2*1024*1024)
+      expect(
+        notifyClient.prepareUpload(file, {isCsv: true})
+      ).contains({is_csv: true, confirm_email_before_download: null, retention_period: null})
+    });
+
+    it('should imply isCsv=false from empty options', () => {
+      let file = Buffer.alloc(2*1024*1024)
+      expect(
+        notifyClient.prepareUpload(file, {})
+      ).contains({is_csv: false, confirm_email_before_download: null, retention_period: null})
+    });
+
+    it('should allow send a file email confirmation to be set', () => {
+      let file = Buffer.alloc(2*1024*1024)
+      expect(
+        notifyClient.prepareUpload(file, {confirmEmailBeforeDownload: true})
+      ).contains({is_csv: false, confirm_email_before_download: true, retention_period: null})
+    });
+
+    it('should allow custom retention periods to be set', () => {
+      let file = Buffer.alloc(2*1024*1024)
+      expect(
+        notifyClient.prepareUpload(file, {retentionPeriod: "52 weeks"})
+      ).contains({is_csv: false, confirm_email_before_download: null, retention_period: '52 weeks'})
+    });
   });
@@ -193,0 +228,0 @@

New alerts

Environment variable access

Supply chain risk

Package accesses environment variables, which may be a sign of credential stuffing or data theft.

Found 1 instance in 1 package

Fixed alerts

Environment variable access

Supply chain risk

Package accesses environment variables, which may be a sign of credential stuffing or data theft.

Found 12 instances in 1 package

Improved metrics

Total package byte prevSize

234263

increased by3.06%

Lines of code

2063

increased by2.23%

Worsened metrics

Number of low supply chain risk alerts

25

increased by92.31%

No dependency changes