Restore comments lost when converting CoffeeScript to JavaScript

2 files changed, 25 insertions, 0 deletions

diff --git a/app/assets/javascripts/u2f/authenticate.js b/app/assets/javascripts/u2f/authenticate.js
index 9ba847fb0c2..ce2930c7fc7 100644
--- a/app/assets/javascripts/u2f/authenticate.js
+++ b/app/assets/javascripts/u2f/authenticate.js
@@ -1,3 +1,7 @@
+// Authenticate U2F (universal 2nd factor) devices for users to authenticate with.
+//
+// State Flow #1: setup -> in_progress -> authenticated -> POST to server
+// State Flow #2: setup -> in_progress -> error -> setup
 (function() {
   var bind = function(fn, me){ return function(){ return fn.apply(me, arguments); }; };
 
@@ -15,6 +19,17 @@
       this.appId = u2fParams.app_id;
       this.challenge = u2fParams.challenge;
       this.signRequests = u2fParams.sign_requests.map(function(request) {
+        // The U2F Javascript API v1.1 requires a single challenge, with
+        // _no challenges per-request_. The U2F Javascript API v1.0 requires a
+        // challenge per-request, which is done by copying the single challenge
+        // into every request.
+        //
+        // In either case, we don't need the per-request challenges that the server
+        // has generated, so we can remove them.
+        //
+        // Note: The server library fixes this behaviour in (unreleased) version 1.0.0.
+        // This can be removed once we upgrade.
+        // https://github.com/castle/ruby-u2f/commit/103f428071a81cd3d5f80c2e77d522d5029946a4
         return _(request).omit('challenge');
       });
     }
@@ -41,6 +56,7 @@
       })(this), 10);
     };
 
+    // Rendering #
     U2FAuthenticate.prototype.templates = {
       "notSupported": "#js-authenticate-u2f-not-supported",
       "setup": '#js-authenticate-u2f-setup',
@@ -75,6 +91,8 @@
 
     U2FAuthenticate.prototype.renderAuthenticated = function(deviceResponse) {
       this.renderTemplate('authenticated');
+      // Prefer to do this instead of interpolating using Underscore templates
+      // because of JSON escaping issues.
       return this.container.find("#js-device-response").val(deviceResponse);
     };
 
diff --git a/app/assets/javascripts/u2f/register.js b/app/assets/javascripts/u2f/register.js
index c87e0840df3..926912fa988 100644
--- a/app/assets/javascripts/u2f/register.js
+++ b/app/assets/javascripts/u2f/register.js
@@ -1,3 +1,7 @@
+// Register U2F (universal 2nd factor) devices for users to authenticate with.
+//
+// State Flow #1: setup -> in_progress -> registered -> POST to server
+// State Flow #2: setup -> in_progress -> error -> setup
 (function() {
   var bind = function(fn, me){ return function(){ return fn.apply(me, arguments); }; };
 
@@ -39,6 +43,7 @@
       })(this), 10);
     };
 
+    // Rendering #
     U2FRegister.prototype.templates = {
       "notSupported": "#js-register-u2f-not-supported",
       "setup": '#js-register-u2f-setup',
@@ -73,6 +78,8 @@
 
     U2FRegister.prototype.renderRegistered = function(deviceResponse) {
       this.renderTemplate('registered');
+      // Prefer to do this instead of interpolating using Underscore templates
+      // because of JSON escaping issues.
       return this.container.find("#js-device-response").val(deviceResponse);
     };