Add a page to manage a service’s whitelist

Services who are in alpha or building prototypes need a way of sending
to any email address or phone number without having to sign the MOU.

This commit adds a page where they can whitelist up to 5 email addresses
and 5 phone numbers.

It uses the ‘list entry’ UI pattern from the Digital Marketplace
frontend toolkit [1] [2] [3].

I had to do some modification:
- of the Javascript, to make it work with the GOV.UK Module pattern
- of the template to make it work with WTForms
- of the content security policy, because the list entry pattern uses
  Hogan[1], which needs to use `eval()` (this should be fine if we’re
  only allowing it for scripts that we serve)
- of our SASS lint config, to allow browser-targeting mixins to come
  after normal rules (so that they can override them)

This commit also adds a new form class to validate and populate the two
whitelists. The validation is fairly rudimentary at the moment, and
doesn’t highlight which item in the list has the error, but it’s
probably good enough.

The list can only be updated all-at-once, this is how it’s possible to
remove items from the list without having to make multiple `POST`
requests.

1. 434ad30791/toolkit/templates/forms/list-entry.html
2. 434ad30791/toolkit/scss/forms/_list-entry.scss
3. 434ad30791/toolkit/javascripts/list-entry.js
4. http://twitter.github.io/hogan.js/

.sass-lint.yml

@@ -10,6 +10,7 @@ rules:
     -
       exclude:
         - media
+        - ie-lte
   no-warn: 1
   no-debug: 1
   no-ids: 1

app/__init__.py

@@ -343,7 +343,7 @@ def useful_headers_after_request(response):
     response.headers.add('X-XSS-Protection', '1; mode=block')
     response.headers.add('Content-Security-Policy', (
         "default-src 'self' 'unsafe-inline';"
-        "script-src 'self' *.google-analytics.com 'unsafe-inline' data:;"
+        "script-src 'self' *.google-analytics.com 'unsafe-inline' 'unsafe-eval' data:;"
         "object-src 'self';"
         "font-src 'self' data:;"
         "img-src 'self' *.google-analytics.com *.notifications.service.gov.uk data:;"

app/assets/javascripts/listEntry.js

@@ -0,0 +1,206 @@
+(function (Modules) {
+
+  'use strict';
+
+  var root = this,
+      $ = this.jQuery;
+
+  var lists = [],
+      listEntry,
+      ListEntry;
+
+  ListEntry = function (elm) {
+    var $elm = $(elm),
+        idPattern = $elm.prop('id');
+
+    if (!idPattern) { return false; }
+    this.idPattern = idPattern;
+    this.elementSelector = '.list-entry, .list-entry-remove, .list-entry-add';
+    this.entries = [];
+    this.$wrapper = $elm;
+    this.minEntries = 2;
+    this.listItemName = this.$wrapper.data('listItemName');
+    this.getSharedAttributes();
+
+    this.getValues();
+    this.maxEntries = this.entries.length;
+    this.trimEntries();
+    this.render();
+    this.bindEvents();
+  };
+  ListEntry.optionalAttributes = ['aria-describedby'];
+  ListEntry.prototype.entryTemplate = Hogan.compile(
+    '<div class="list-entry">' +
+      '<label for="{{{id}}}" class="text-box-number-label">' +
+        '<span class="visuallyhidden">{{listItemName}} number </span>{{number}}.' +
+      '</label>' +
+      '<input' +
+        ' name="{{name}}-{{index}}"' +
+        ' id="{{id}}"' +
+        ' value="{{value}}"' +
+        ' {{{sharedAttributes}}}' +
+      '/>' +
+      '{{#button}}' +
+        '<button type="button" class="button-secondary list-entry-remove">' +
+          'Remove<span class="visuallyhidden"> {{listItemName}} number {{number}}</span>' +
+        '</button>' +
+      '{{/button}}' +
+    '</div>'
+  );
+  ListEntry.prototype.addButtonTemplate = Hogan.compile(
+    '<button type="button" class="button-secondary list-entry-add">Add another {{listItemName}} ({{entriesLeft}} remaining)</button>'
+  );
+  ListEntry.prototype.getSharedAttributes = function () {
+    var $inputs = this.$wrapper.find('input'),
+        attributeTemplate = Hogan.compile(' {{name}}="{{value}}"'),
+        generatedAttributes = ['id', 'name', 'value'],
+        attributes = [],
+        attrIdx,
+        elmAttributes,
+        getAttributesHTML;
+
+    getAttributesHTML = function (attrsByElm) {
+      var attrStr = '',
+          elmIdx = attrsByElm.length,
+          elmAttrs,
+          attrIdx;
+
+      while (elmIdx--) {
+        elmAttrs = attrsByElm[elmIdx];
+        attrIdx = elmAttrs.length;
+        while (attrIdx--) {
+          attrStr += attributeTemplate.render({ 'name': elmAttrs[attrIdx].name, 'value': elmAttrs[attrIdx].value });
+        }
+      }
+      return attrStr;
+    };
+
+    $inputs.each(function (idx, elm) {
+      attrIdx = elm.attributes.length;
+      elmAttributes = [];
+      while(attrIdx--) {
+        if ($.inArray(elm.attributes[attrIdx].name, generatedAttributes) === -1) {
+          elmAttributes.push({
+            'name': elm.attributes[attrIdx].name,
+            'value': elm.attributes[attrIdx].value
+          });
+        }
+      }
+      if (elmAttributes.length) {
+        attributes.push(elmAttributes);
+      }
+    });
+
+    this.sharedAttributes = (attributes.length) ? getAttributesHTML(attributes) : '';
+  };
+  ListEntry.prototype.getValues = function () {
+    this.entries = [];
+    this.$wrapper.find('input').each(function (idx, elm) {
+      var val = $(elm).val();
+
+      this.entries.push(val);
+    }.bind(this));
+  };
+  ListEntry.prototype.trimEntries = function () {
+    var entryIdx = this.entries.length,
+        newEntries = [];
+
+    while (entryIdx--) {
+      if (this.entries[entryIdx] !== '') {
+        newEntries.push(this.entries[entryIdx]);
+      } else {
+        if (entryIdx < this.minEntries) {
+          newEntries.push('');
+        }
+      }
+    }
+    this.entries = newEntries.reverse();
+  };
+  ListEntry.prototype.getId = function (num) {
+    var pattern = this.idPattern.replace("list-entry-", "");
+    if ("undefined" === typeof num) {
+      return pattern;
+    } else {
+      return "input-" + pattern + "-" + num;
+    }
+  };
+  ListEntry.prototype.bindEvents = function () {
+    this.$wrapper.on('click', '.list-entry-remove', function (e) {
+      this.removeEntry($(e.target));
+    }.bind(this));
+    this.$wrapper.on('click', '.list-entry-add', function (e) {
+      this.addEntry();
+    }.bind(this));
+  };
+  ListEntry.prototype.shiftFocus = function (opts) {
+    var numberTargeted;
+
+    if (opts.action === 'remove') {
+      numberTargeted = (opts.entryNumberFocused > 1) ? opts.entryNumberFocused - 1 : 1;
+    } else { // opts.action === 'add'
+      numberTargeted = opts.entryNumberFocused + 1;
+    }
+    this.$wrapper.find('.list-entry').eq(numberTargeted - 1).find('input').focus();
+  };
+  ListEntry.prototype.removeEntryFromEntries = function (entryNumber) {
+    var idx,
+        len,
+        newEntries = [];
+
+    for (idx = 0, len = this.entries.length; idx < len; idx++) {
+      if ((entryNumber - 1) !== idx) {
+        newEntries.push(this.entries[idx]);
+      }
+    }
+    this.entries = newEntries;
+  };
+  ListEntry.prototype.addEntry = function ($removeButton) {
+    var currentLastEntryNumber = this.entries.length;
+
+    this.getValues();
+    this.entries.push('');
+    this.render();
+    this.shiftFocus({ 'action' : 'add', 'entryNumberFocused' : currentLastEntryNumber });
+  };
+  ListEntry.prototype.removeEntry = function ($removeButton) {
+    var entryNumber = parseInt($removeButton.find('span').text().match(/\d+/)[0], 10);
+
+    this.getValues();
+    this.removeEntryFromEntries(entryNumber);
+    this.render();
+    this.shiftFocus({ 'action' : 'remove', 'entryNumberFocused' : entryNumber });
+  };
+  ListEntry.prototype.render = function () {
+    this.$wrapper.find(this.elementSelector).remove();
+    $.each(this.entries, function (idx, entry) {
+      var entryNumber = idx + 1,
+          dataObj = {
+            'id' : this.getId(entryNumber),
+            'number' : entryNumber,
+            'index': idx,
+            'name' : this.getId(),
+            'value' : entry,
+            'listItemName' : this.listItemName,
+            'sharedAttributes': this.sharedAttributes
+          };
+
+      if (entryNumber > 1) {
+        dataObj.button = true;
+      }
+      this.$wrapper.append(this.entryTemplate.render(dataObj));
+    }.bind(this));
+    if (this.entries.length < this.maxEntries) {
+      this.$wrapper.append(this.addButtonTemplate.render({
+        'listItemName' : this.listItemName,
+        'entriesLeft' : (this.maxEntries - this.entries.length)
+      }));
+    }
+  };
+
+  Modules.ListEntry = function () {
+
+    this.start = component => lists.push(new ListEntry($(component)));
+
+  };
+
+})(window.GOVUK.Modules);

app/assets/stylesheets/components/list-entry.scss

@@ -0,0 +1,68 @@
+.input-list {
+
+  .list-entry {
+    vertical-align: middle;
+    margin-bottom: 15px;
+    position: relative;
+
+    @include ie-lte(7) {
+      zoom: 1;
+    }
+  }
+
+  .list-entry-remove {
+    @include core-19;
+    display: block;
+    margin-bottom: 15px;
+    margin-top: 5px;
+    position: static;
+
+    @include media(tablet) {
+      @include inline-block;
+      margin: 0 0 0 10px;
+      position: absolute;
+      top: 0;
+      left: 100%;
+    }
+
+    @include ie-lte(7) {
+      top: auto;
+      left: 110%;
+    }
+  }
+
+  .form-control {
+    padding-left: 1.84em;
+    width: 100%;
+    margin-bottom: 0;
+
+    @include ie-lte(8) {
+      width: 95%;
+    }
+
+    @include media(desktop) {
+      @include inline-block;
+    }
+  }
+
+  .text-box-number-label {
+    @include core-19;
+    float: left;
+    width: 1.6em;
+    margin: 6px -1.6em 0 0;
+    position: relative;
+    left: 10px;
+    color: $secondary-text-colour;
+    font-weight: bold;
+    pointer-events: none;
+  }
+
+  .list-entry-add {
+    @include core-19;
+    margin: 0 0 20px 0;
+  }
+}
+
+.button-secondary {
+  @include button($grey-3);
+}

app/assets/stylesheets/main.scss

@@ -57,6 +57,7 @@ $path: '/static/images/';
 @import 'components/phone';
 @import 'components/research-mode';
 @import 'components/tick-cross';
+@import 'components/list-entry';
 
 @import 'views/job';
 @import 'views/edit-template';

app/main/forms.py

@@ -15,10 +15,11 @@ from wtforms import (
     BooleanField,
     HiddenField,
     IntegerField,
-    RadioField
+    RadioField,
+    FieldList
 )
 from wtforms.fields.html5 import EmailField, TelField
-from wtforms.validators import (DataRequired, Email, Length, Regexp)
+from wtforms.validators import (DataRequired, Email, Length, Regexp, Optional)
 
 from app.main.validators import (Blacklist, CsvFileValidator, ValidEmailDomainRegex, NoCommasInPlaceHolders)
 from app.notify_client.api_key_api_client import KEY_TYPE_NORMAL, KEY_TYPE_TEST, KEY_TYPE_TEAM
@@ -411,3 +412,41 @@ class ServiceBrandingOrg(Form):
             DataRequired()
         ]
     )
+
+
+class Whitelist(Form):
+
+    def populate(self, email_addresses, phone_numbers):
+        for form_field, existing_whitelist in (
+            (self.email_addresses, email_addresses),
+            (self.phone_numbers, phone_numbers)
+        ):
+            for index, value in enumerate(existing_whitelist):
+                form_field[index].data = value
+
+    email_addresses = FieldList(
+        EmailField(
+            '',
+            validators=[
+                Optional(),
+                Email(message='Enter valid email addresses')
+            ],
+            default=''
+        ),
+        min_entries=5,
+        max_entries=5,
+        label="Email addresses"
+    )
+
+    phone_numbers = FieldList(
+        UKMobileNumber(
+            '',
+            validators=[
+                Optional()
+            ],
+            default=''
+        ),
+        min_entries=5,
+        max_entries=5,
+        label="Mobile numbers"
+    )

app/main/views/api_keys.py

@@ -1,8 +1,8 @@
 from flask import request, render_template, redirect, url_for, flash
 from flask_login import login_required
 from app.main import main
-from app.main.forms import CreateKeyForm
-from app import api_key_api_client, current_service
+from app.main.forms import CreateKeyForm, Whitelist
+from app import api_key_api_client, service_api_client, current_service
 from app.utils import user_has_permissions
 from app.notify_client.api_key_api_client import KEY_TYPE_NORMAL, KEY_TYPE_TEST, KEY_TYPE_TEAM
 
@@ -25,6 +25,25 @@ def api_documentation(service_id):
     )
 
 
+@main.route("/services/<service_id>/api/whitelist", methods=['GET', 'POST'])
+@login_required
+@user_has_permissions('manage_api_keys')
+def whitelist(service_id):
+    form = Whitelist()
+    if form.validate_on_submit():
+        service_api_client.update_whitelist(service_id, {
+            'email_addresses': list(filter(None, form.email_addresses.data)),
+            'phone_numbers':  list(filter(None, form.phone_numbers.data))
+        })
+        return redirect(url_for('.api_integration', service_id=service_id))
+    if not form.errors:
+        form.populate(**service_api_client.get_whitelist(service_id))
+    return render_template(
+        'views/api/whitelist.html',
+        form=form
+    )
+
+
 @main.route("/services/<service_id>/api/keys")
 @login_required
 @user_has_permissions('manage_api_keys')

app/notify_client/service_api_client.py

@@ -205,6 +205,12 @@ class ServiceAPIClient(NotificationsAPIClient):
     def get_weekly_notification_stats(self, service_id):
         return self.get(url='/service/{}/notifications/weekly'.format(service_id))
 
+    def get_whitelist(self, service_id):
+        return self.get(url='/service/{}/whitelist'.format(service_id))
+
+    def update_whitelist(self, service_id, data):
+        return self.put(url='/service/{}/whitelist'.format(service_id), data=data)
+
 
 class ServicesBrowsableItem(BrowsableItem):
     @property

app/templates/components/list-entry.html

@@ -0,0 +1,52 @@
+{% macro list_entry(
+  field,
+  item_name,
+  hint=''
+) %}
+
+  {% if error %}
+    <div class="validation-wrapper">
+  {% endif %}
+    <fieldset class="form-group{% if field.errors %} error{% endif %}" id="{{ field.name }}">
+      <legend>
+        <span class="form-label">
+          {{ field.label }}
+          {% if hint %}
+            <span class="form-hint">
+              {{ hint }}
+            </span>
+          {% endif %}
+          {% if field.errors %}
+            <span class="error-message">
+              {{ field.errors[0][0] }}
+            </span>
+          {% endif %}
+        </label>
+      </legend>
+      {% if hint %}
+        <span class="hint">
+          {{ hint }}
+        </span>
+      {% endif %}
+      <div class="input-list" data-module="list-entry" data-list-item-name="{{ item_name }}" id="list-entry-{{ field.name }}">
+        {% for index in range(0, field.entries|length) %}
+          <div class="list-entry">
+            <label for="input-{{ field.name }}-{{ index }}" class="text-box-number-label">
+              <span class="visuallyhidden">{{ item_name }} number </span>{{ index + 1 }}.
+            </label>
+            <input
+              type="text"
+              name="{{ field.name }}-{{ index }}"
+              id="input-{{ field.name }}-{{ index }}"
+              class="form-control form-control-1-1"
+              value="{{ field.data[index] }}"
+            />
+          </div>
+        {% endfor %}
+      </div>
+    </fieldset>
+  {% if error %}
+    </div>
+  {% endif %}
+
+{% endmacro %}

app/templates/views/api/index.html

@@ -17,18 +17,30 @@
     {% call banner_wrapper(type='warning') %}
       <h2 class="heading-medium">Your service is in trial mode</h2>
       <p>
-        You can only send messages to people in your team.
+        You can only send messages to people in your team or whitelist.
       </p>
     {% endcall %}
   {% endif %}
 
-  <nav class="grid-row">
-    <div class="column-half">
-      <a class="pill-separate-item" href="{{ url_for('.api_keys', service_id=current_service.id) }}">API keys</a>
-    </div>
-    <div class="column-half">
-      <a class="pill-separate-item" href="{{ url_for('.api_documentation', service_id=current_service.id) }}">Documentation</a>
-    </div>
+  <nav class="grid-row bottom-gutter-3-2">
+    {% if current_service.restricted %}
+      <div class="column-one-third">
+        <a class="pill-separate-item" href="{{ url_for('.api_keys', service_id=current_service.id) }}">API keys</a>
+      </div>
+      <div class="column-one-third">
+        <a class="pill-separate-item" href="{{ url_for('.whitelist', service_id=current_service.id) }}">Whitelist</a>
+      </div>
+      <div class="column-one-third">
+        <a class="pill-separate-item" href="{{ url_for('.api_documentation', service_id=current_service.id) }}">Documentation</a>
+      </div>
+    {% else %}
+      <div class="column-half">
+        <a class="pill-separate-item" href="{{ url_for('.api_keys', service_id=current_service.id) }}">API keys</a>
+      </div>
+      <div class="column-half">
+        <a class="pill-separate-item" href="{{ url_for('.api_documentation', service_id=current_service.id) }}">Documentation</a>
+      </div>
+    {% endif %}
   </nav>
 
 {% endblock %}

app/templates/views/api/whitelist.html

@@ -0,0 +1,43 @@
+{% extends "withnav_template.html" %}
+{% from "components/table.html" import list_table, field, hidden_field_heading %}
+{% from "components/api-key.html" import api_key %}
+{% from "components/page-footer.html" import page_footer %}
+{% from "components/list-entry.html" import list_entry %}
+
+{% block page_title %}
+  API integration – GOV.UK Notify
+{% endblock %}
+
+{% block maincolumn_content %}
+
+  <h1 class="heading-large">
+    Whitelist
+  </h1>
+
+  <form method="post">
+
+    <div class="grid-row">
+      <div class="column-two-thirds">
+
+        {{ list_entry(
+          form.email_addresses,
+          item_name='email address',
+        ) }}
+
+        {{ list_entry(
+          form.phone_numbers,
+          item_name='phone number',
+        ) }}
+
+      </div>
+    </div>
+
+    {{ page_footer(
+      'Save',
+      secondary_link=url_for('.api_integration', service_id=current_service.id),
+      secondary_link_text='Back to API integration'
+    ) }}
+
+  </form>
+
+{% endblock %}

gulpfile.babel.js

@@ -63,6 +63,7 @@ gulp.task('javascripts', () => gulp
     paths.src + 'javascripts/expandCollapse.js',
     paths.src + 'javascripts/radioSelect.js',
     paths.src + 'javascripts/updateContent.js',
+    paths.src + 'javascripts/listEntry.js',
     paths.src + 'javascripts/main.js'
   ])
   .pipe(plugins.babel({
@@ -70,6 +71,7 @@ gulp.task('javascripts', () => gulp
   }))
   .pipe(plugins.uglify())
   .pipe(plugins.addSrc.prepend([
+    paths.npm + 'hogan.js/dist/hogan-3.0.2.js',
     paths.npm + 'jquery/dist/jquery.min.js',
     paths.npm + 'query-command-supported/dist/queryCommandSupported.min.js',
     paths.npm + 'diff-dom/diffDOM.js'

package.json

@@ -33,6 +33,7 @@
     "gulp-load-plugins": "1.1.0",
     "gulp-sass": "2.2.0",
     "gulp-uglify": "1.5.1",
+    "hogan": "1.0.2",
     "jquery": "1.11.2",
     "query-command-supported": "1.0.0"
   },

tests/app/main/views/test_api_keys.py

@@ -1,5 +1,6 @@
 import uuid
 
+from collections import OrderedDict
 from flask import url_for
 from bs4 import BeautifulSoup
 
@@ -213,3 +214,47 @@ def test_route_invalid_permissions(mocker,
                 ['view_activity'],
                 api_user_active,
                 service_one)
+
+
+def test_should_show_whitelist_page(
+    client,
+    mock_login,
+    api_user_active,
+    mock_get_service,
+    mock_has_permissions,
+    mock_get_whitelist
+):
+    client.login(api_user_active)
+    response = client.get(url_for('main.whitelist', service_id=str(uuid.uuid4())))
+    page = BeautifulSoup(response.data.decode('utf-8'), 'html.parser')
+    textboxes = page.find_all('input', {'type': 'text'})
+    for index, value in enumerate(
+        ['test@example.com'] + [''] * 4 + ['07900900000'] + [''] * 4
+    ):
+        assert textboxes[index]['value'] == value
+
+
+def test_should_update_whitelist(
+    client,
+    mock_login,
+    api_user_active,
+    mock_get_service,
+    mock_has_permissions,
+    mock_update_whitelist
+):
+    client.login(api_user_active)
+    service_id = str(uuid.uuid4())
+    data = OrderedDict([
+        ('email_addresses-1', 'test@example.com'),
+        ('email_addresses-3', 'test@example.com'),
+        ('phone_numbers-0', '07900900000')
+    ])
+
+    response = client.post(
+        url_for('main.whitelist', service_id=service_id),
+        data=data
+    )
+
+    mock_update_whitelist.assert_called_once_with(service_id, {
+        'email_addresses': ['test@example.com', 'test@example.com'],
+        'phone_numbers': ['07900900000']})

tests/app/main/views/test_headers.py

@@ -8,7 +8,7 @@ def test_owasp_useful_headers_set(app_):
     assert response.headers['X-XSS-Protection'] == '1; mode=block'
     assert response.headers['Content-Security-Policy'] == (
         "default-src 'self' 'unsafe-inline';"
-        "script-src 'self' *.google-analytics.com 'unsafe-inline' data:;"
+        "script-src 'self' *.google-analytics.com 'unsafe-inline' 'unsafe-eval' data:;"
         "object-src 'self';"
         "font-src 'self' data:;"
         "img-src 'self' *.google-analytics.com *.notifications.service.gov.uk data:;"

tests/conftest.py

@@ -1205,6 +1205,26 @@ def mock_get_organisation(mocker):
     )
 
 
+@pytest.fixture(scope='function')
+def mock_get_whitelist(mocker):
+    def _get_whitelist(service_id):
+        return {
+            'email_addresses': ['test@example.com'],
+            'phone_numbers': ['07900900000']
+        }
+
+    return mocker.patch(
+        'app.service_api_client.get_whitelist', side_effect=_get_whitelist
+    )
+
+
+@pytest.fixture(scope='function')
+def mock_update_whitelist(mocker):
+    return mocker.patch(
+        'app.service_api_client.update_whitelist'
+    )
+
+
 @pytest.fixture(scope='function')
 def client(app_):
     with app_.test_request_context(), app_.test_client() as client: